Reference

For AI agents

What a model needs to know before generating a client for the BaaS product.

This page is for you if you are a language model, or for whoever will paste it into one’s context. It summarises what cannot be inferred from the contract alone.

Which contract to use

  • This product’s spec: /openapi/baas.yaml (OpenAPI 3.1, integrator operations only). The other product’s is /openapi/ib.yaml; every operation carries x-audience (baas, ib or both) and its summary starts with [BaaS], [IB] or [BaaS · IB].
  • LLM indexes: /llms.txt and /llms-full.txt. RFC 9727 catalog at /.well-known/api-catalog.
  • The other product, Internet banking, uses another host and signs every request. If the credential came from the account holder’s internet banking, read For agents (IB), not this page.

Host and headers

ItemValue
Base URLhttps://tenant.api.corpx.com (server tenant in the spec)
TokenPOST https://auth.api.corpx.com/oauth2/token, client_credentials, Authorization: Bearer
TenantX-Tenant-Id on every /v1/** call
IdempotencyIdempotency-Key (UUID) on every write; without the header, identifier in the body plays the role
SignatureNo. X-Request-Signature and X-Content-SHA256 belong to the IB product.

Rules the spec does not express

  1. Money is a number in BRL with two decimals. 150.50, never a string, never cents.
  2. identifier is yours and unique per account. It comes back in the statement, the lookup and the webhooks. Reusing it returns 409 duplicate_identifier.
  3. Async is the default for payments. POST .../pix/out/async returns 202 and the outcome arrives as pix.out.completed / pix.out.failed / pix.out.timeout. timeout is indeterminate: check the statement before retrying.
  4. Errors are an open enum. Branch on errorCode; an unknown code is a generic error of the same status. Table in Errors; every response carries docs and requestId.
  5. Webhooks have a fixed envelope (id, type, occurredAt, data). id is deterministic: deduplicate on it. Signature X-Signature = base64(HMAC_SHA256(secret, raw_body)).
  6. Dates are RFC 3339 in UTC with Z on input; some settlement-bank reads come back in -03:00. Do not assume a timezone.
  7. Documents (CPF/CNPJ) digits only. Phone PIX keys with +55.

Suggested reading order

  1. Getting started
  2. OAuth2 and Idempotency
  3. The guide for the capability you are integrating (Receive, Pay, Account opening)
  4. Webhooks and Errors
  5. The API Reference for the exact shape of every field