Convenções da API

Esta página reúne as convenções transversais que valem para todos os recursos da API Selectwin. Conhecê-las evita os erros de integração mais comuns.

Nomenclatura — camelCase

Todos os campos de requisição e resposta usam camelCase (firstName, createdAt, unitPrice, externalReference). Não há campos em snake_case nas superfícies públicas.

Valores monetários — centavos (inteiros)

Todo valor monetário é um inteiro em centavos. Nunca use ponto flutuante para dinheiro.

Aplica-se a amount, unitPrice, oldPrice, costPerItem, fee, grossAmount, etc. Converta para centavos antes de enviar e divida por 100 apenas para exibir.

Moeda

Use o código ISO 4217 em maiúsculas. Atualmente a API opera em BRL (Real brasileiro).

Datas e horários — ISO 8601 em UTC

Todos os timestamps são ISO 8601 com timezone UTC (sufixo Z):

2026-04-12T17:56:33.000Z

• Campos de data-hora: createdAt, updatedAt, paidAt, approvedAt, dueDate, expectedOn, …
• Converta para o fuso do usuário apenas na exibição.
• Campos de data (sem hora), quando existirem, usam YYYY-MM-DD.

Identificadores (IDs)

Todo recurso tem um identificador público no formato prefixo_valor (ex.: cus_01hqzvabc). O prefixo indica o tipo do recurso.

🔑 Trate os IDs como opacos. Armazene a string inteira; não faça parsing, não confie no comprimento e não construa IDs manualmente. O prefixo é uma conveniência para leitura humana — a lógica do seu sistema deve tratar o ID como uma string opaca e estável.

Prefixos dos recursos públicos (para referência):

Nas respostas, o ID público é sempre exposto como id (e como <recurso>Id quando referenciado por outro recurso, ex.: customerId, transactionId). O identificador numérico interno nunca é exposto. Os IDs nos exemplos dos guias são ilustrativos — confie nesta tabela e no campo id real da resposta.

null vs. campo ausente

• Um campo presente com valor null significa "sem valor" (ex.: paidAt: null = ainda não pago).
• Em respostas de lista (data[]), os itens são projeções leves — alguns campos do objeto completo são omitidos. Para o objeto completo, consulte o recurso individual (GET .../{id}).

Requisições

• Corpo das requisições em JSON.
• Use externalReference e metadata (objeto livre) para correlacionar recursos com o seu sistema.

Respostas

• Sucesso: o corpo é o objeto do recurso (ou o objeto paginado em listagens). Veja Paginação e o padrão HATEOAS (_links) em Recursos.
• Erro: envelope padrão com error.code estável — veja Tratamento de Erros e o Catálogo de Códigos de Erro.
• Webhooks: verifique sempre a assinatura — veja Verificando Assinaturas de Webhook.

Resumo