Recursos para IA
Possíveis erros
Ao integrar o Split de Pagamentos 1:N, a API pode retornar erros de validação com códigos e mensagens específicos. A seguir são descritos os erros por tema e o formato de resposta.
Todas as validações são realizadas em sequência; a primeira validação que falha interrompe o processo.
Mapeamento de códigos de erro
Os erros utilizam tipos base que se traduzem em códigos de status HTTP:
| Tipo de erro base | Código de status HTTP | Descrição |
| TypeErrorClient | 400 | Bad Request. Erros do cliente com mensagens específicas para problemas corrigíveis. |
| TypeErrorInvalidInput | 400 | Bad Request. Dados de entrada inválidos. |
| TypeErrorUnprocessable | 422 | Unprocessable Entity. Erros de validação (validação de usuário, validação de compliance). Utiliza-se para distinguir de erros do cliente (400). |
| TypeErrorNotFound | 404 | Not Found. Recurso não encontrado. |
| TypeErrorInternal | 500 | Internal Server Error. Erros do lado do servidor. |
| TypeErrorUnavailable | 503 | Service Unavailable. Retornado quando os serviços externos (Busca de Usuários, KYC) não estão disponíveis. |
Validações de receptores
Validações relacionadas aos receptores (vendedores) no split.
| Nome da validação | Código de erro | Status HTTP | Mensagem de erro | Descrição |
| Falta receptor primário | TypeErrorClient | 400 | "primary receiver must be present in the split" | Pelo menos um receptor deve estar marcado como primário (geralmente o vendedor que iniciou o split). O receptor primário (vendedor primário) é o dono da aplicação usada na integração. |
| Mínimo de receptores secundários | TypeErrorClient | 400 | "minimum of 1 secondary receiver is required" | É necessário pelo menos um receptor secundário. |
| Receptores duplicados | TypeErrorClient | 400 | "there are users duplicated" | Nenhum ID de usuário pode aparecer mais de uma vez na lista de receptores. |
| Limite de vendedores excedido | TypeErrorClient | 400 | "split contains more sellers than allowed" | O número total de receptores não pode exceder o máximo configurado (quando MaxSplitSellers está configurado). O máximo permitido é de 10 vendedores secundários por order. |
Validações de valor
Validações para valores do split. Algumas se aplicam apenas a splits por percentual e outras apenas a splits fixos.
| Nome da validação | Código de erro | Status HTTP | Mensagem de erro | Descrição |
| Faixa de percentual inválida | TypeErrorClient | 400 | "percentage must be between 1 and 100" | O percentual de cada receptor deve estar entre 1 e 100 (apenas para splits por percentual). |
| Soma de percentual inválida | TypeErrorClient | 400 | "percentages must add up to 100.00" | A soma de todos os percentuais dos receptores deve ser exatamente 100,00 (apenas para splits por percentual). |
| Soma de valor fixo inválida | TypeErrorClient | 400 | "the sum of the amounts for the receivers must be equal to the total amount of the split" | A soma de todos os valores dos receptores deve ser igual ao valor total do split (apenas para splits fixos). |
Validações de pagamento
Validações que se aplicam aos métodos de pagamento.
| Nome da validação | Código de erro | Status HTTP | Mensagem de erro | Descrição |
| Tipo de meio de pagamento inválido | TypeErrorClient | 400 | "invalid payment method type" | O tipo de meio de pagamento deve estar na lista permitida configurada no sistema. Os meios de pagamento permitidos são cartão de crédito e débito. |
Validações de itens
Validações que só se aplicam quando o split inclui itens.
| Nome da validação | Código de erro | Status HTTP | Mensagem de erro | Descrição |
| Códigos externos de itens duplicados | TypeErrorClient | 400 | "items list contains duplicate external code" | Não pode haver dois itens com o mesmo external_code. |
| Referência de item inválida | TypeErrorClient | 400 | "receiver references non-existent item" | Todas as referências de itens nos receptores devem corresponder a itens existentes no split. |
Validações de usuário
Validações externas realizadas contra o serviço de Busca de Usuários.
| Nome da validação | Código de erro | Status HTTP | Mensagem de erro | Descrição |
| Usuário não encontrado | TypeErrorUnprocessable | 422 | "user validation error" | O ID de usuário não existe no sistema (o serviço de usuário retorna 404). |
| Usuário inativo | TypeErrorUnprocessable | 422 | "user validation error" | O usuário existe, mas não está em estado "ativo" (guest, deactive, pending ou vazio). |
| Site do usuário não coincide | TypeErrorUnprocessable | 422 | "user validation error" | O ID do site do usuário não coincide com o ID do site do vendedor. |
| Serviço de usuário indisponível | TypeErrorUnavailable | 503 | "service unavailable" | Erros de rede ou timeout ao chamar o serviço de usuário. |
| Vendedor usando modo PNF | TypeErrorUnprocessable | 422 | "seller is using pnf mode, blocked" | A transação é bloqueada se o vendedor estiver operando em modo PNF (Pagamento Não Fluxo). |
Validações de compliance KYC
Validações externas realizadas contra o serviço de Compliance KYC.
| Nome da validação | Código de erro | Status HTTP | Mensagem de erro | Descrição |
| Falha na verificação de compliance KYC | TypeErrorUnprocessable | 422 | "compliance validation error" | O usuário não está em conformidade (o estado não é "compliant" nem "skip_compliance"). |
| Serviço KYC indisponível | TypeErrorUnavailable | 503 | "service unavailable" | Erros de rede ou timeout ao chamar o serviço de KYC. |
Erros internos
| Nome da validação | Código de erro | Status HTTP | Mensagem de erro | Descrição |
| Erro interno do servidor | TypeErrorInternal | 500 | "internal server error" | Erro inesperado do lado do servidor. |
Formato da resposta de erro
Os erros retornam no seguinte formato, com o campo errors como array (podendo estar vazio quando o contexto do erro está descrito na message principal):
Erro do cliente (400)
json
{ "status": 400, "message": "percentages must add up to 100.00", "errors": [] }
Erro de validação (422)
json
{ "status": 422, "message": "user validation error", "errors": [] }
Serviço indisponível (503)
json
{ "status": 503, "message": "service unavailable", "errors": [] }
Erro interno (500)
json
{ "status": 500, "message": "internal server error", "errors": [] }