Comece aqui

Primeiros passos

Cinco etapas para sair do zero à primeira chamada bem-sucedida. O fluxo vale para qualquer produto; só muda o endpoint da etapa 5.

1. Obter credenciais

Solicite acesso ao time de Integrações/Onboarding da UY3. Dependendo do produto e do tipo de integração, você recebe:

Usuário e senha no pool de identidade (AWS Cognito), para fluxos interativos e de backoffice. O MFA (TOTP) é obrigatório e é configurado no backoffice — o portal e as APIs assumem o MFA já ativo.
ApiKey para integrações servidor-a-servidor, quando o produto expõe esse modo.

Guarde os segredos em cofre (Key Vault / Secrets Manager). Nunca versione credenciais em código ou em arquivos de configuração.

2. Identificar a URL base

Cada produto usa a URL base da API que o serve. A URL base específica é indicada na página de integração do produto.

3. Autenticar

Obtenha um JWT Bearer no fluxo Cognito (ou use sua ApiKey, conforme o produto) e envie-o no header de toda requisição:

Authorization: Bearer eyJraWQiOiJ...MASCARADO...QsQ

O passo a passo do fluxo e a validade do token estão em Autenticação.

4. Escolher o produto

Na navegação à esquerda, abra o produto que quer integrar (ex.: Consignado privado, em CaaS Massificados). Cada página abre pelo contexto de negócio e traz o fluxo de integração numerado específico daquele produto, com a referência campo-a-campo dos payloads.

5. Primeira chamada

A criação da operação não é a primeira chamada do fluxo. Ela exige dois identificadores que vêm de etapas anteriores do módulo: o productId do produto contratado (fornecido pelo Onboarding) e o personId do tomador (devolvido pelo cadastro da pessoa). O exemplo abaixo mostra o formato; a ordem em que as chamadas acontecem está na página de cada produto.

Exemplo em Crédito, com dados fictícios:

POST /v1/CreditNote HTTP/1.1
Host: <url-base-da-api>
Authorization: Bearer eyJraWQiOiJ...MASCARADO...QsQ
Content-Type: application/json

{
  "productId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "personId": "9c1e0a72-4d38-4f0b-91ad-7b2c5e6d8f10",
  "amortization": {
    "amortizationType": "Price",
    "requestedAmount": 1500000,
    "numberOfPayments": 24,
    "apr": 1.99,
    "firstPaymentDate": "2026-10-05T00:00:00Z",
    "calculationType": "V360DiasCorridos",
    "paymentPeriodicity": { "every": 1, "periodicity": "Monthly" }
  }
}

São três os campos obrigatórios na raiz — productId, personId e amortization. Dentro de amortization, o tipo Price exige firstPaymentDate, numberOfPayments, calculationType e paymentPeriodicity.

O conteúdo de amortization varia conforme o tipo de operação: cada amortizationType aceita um conjunto próprio de campos, listado no Catálogo de tipos de operação. Campo de outro modelo de cálculo enviado aqui é recusado — confira o nome em uy3_campo antes de enviar, ou na página do tipo.

requestedAmount é inteiro em centavos — 1500000 são R$ 15.000,00. Ver Convenções de dados.

Resposta de sucesso (200, dados fictícios):

{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "Draft"
}

A operação nasce em Draft e percorre uma esteira de status até a liquidação. Os valores possíveis e o que dispara cada transição estão na página de operação de cada produto.

Se algo estiver inválido, a API responde no contrato ProblemDetails:

{
  "type": "https://docs.uy3.com.br/errors/validation",
  "title": "Requisição inválida",
  "status": 400,
  "detail": "O campo 'personId' é obrigatório.",
  "instance": "/v1/CreditNote",
  "traceId": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"
}

Pronto: com a operação criada em Draft, siga o fluxo de integração da página do produto para os próximos passos (consulta, atualização, garantia, submissão para aprovação).