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.

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

#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