> ## Documentation Index
> Fetch the complete documentation index at: https://documentacao.credicarro.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Para desenvolvedores

> Visão técnica da API da Credicarro — ambientes, autenticação, formato de respostas e erros

> [!TIP]
>
> Esta seção é para quem vai **integrar tecnicamente**. Se você quer entender o produto antes, veja [Para lojistas](https://documentacao.credicarro.com.br/pages/concepts/overview.md). Se quer ver a ordem das chamadas, vá direto para o [fluxo de integração](https://documentacao.credicarro.com.br/pages/v2/overview.md).

## Em uma frase

A API da Credicarro é REST, autenticada por Bearer token, com campos JSON em português e o mesmo formato de resposta em toda a superfície — um cliente HTTP e um token já bastam para integrar.

> **Não é a página de referência de endpoints**
>
> Esta página explica os conceitos que atravessam toda a API. Para o contrato de cada endpoint, use as abas **Autenticação**, **Proposta** e **Webhooks**, as [convenções da API](https://documentacao.credicarro.com.br/pages/reference/introduction.md) ou o arquivo [OpenAPI](https://documentacao.credicarro.com.br/openapi.yaml).

## Ambientes

| Ambiente | Base URL | Uso |
| - | - | - |
| Staging | `https://api.staging.credicarro.com.br/integration` | Testes, sem afetar produção — veja [ambiente de desenvolvimento](https://documentacao.credicarro.com.br/pages/development.md) |
| Produção | `https://api.credicarro.com.br/integration` | Propostas reais |

O ambiente é determinado pela URL base que você chama — as credenciais (`ClientId`/`ClientSecret`) são específicas de cada ambiente.

## Autenticação

Toda requisição autenticada usa um Bearer token, obtido via `ClientId`/`ClientSecret` solicitados ao nosso suporte.

```bash theme={null}
curl -X POST https://api.staging.credicarro.com.br/integration/v1/authentication/accesstoken \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "<client-id>", "clientSecret": "<client-secret>" }'
```

> **[Fluxo completo de autenticação](https://documentacao.credicarro.com.br/pages/authentication.md)**
>
> Veja a resposta completa e as boas práticas de segurança.

## Formato das respostas

Os campos JSON são em português. Listas paginadas seguem sempre o mesmo formato:

```json theme={null}
{
  "itens": [ ],
  "pagina": {
    "numero": 1,
    "tamanho": 10,
    "total": 45,
    "tem_proximo": true,
    "tem_anterior": false
  }
}
```

## Erros

As respostas de erro trazem os campos `tipo` (código estável do erro), `titulo`, `status` e `detalhe`. Quando o erro é de um campo, vem também `campo`. As exceções são o `401`, que vem sem corpo, e falhas inesperadas, que podem vir no formato padrão Problem Details.

> **[Formato completo de erro e Idempotency-Key](https://documentacao.credicarro.com.br/pages/errors.md)**
>
> Veja o formato de erro, os status HTTP e o reenvio seguro de operações.

## Idempotência

As rotas de cliente, simulação, proposta e documento aceitam o cabeçalho `Idempotency-Key`: reenviar a mesma chave com o mesmo corpo retorna o resultado original em vez de repetir a operação. No [envio de documentos](https://documentacao.credicarro.com.br/pages/v2/proposal/document.md) o cabeçalho é obrigatório.

## Troubleshooting

> **401 Unauthorized**
>
> O token não foi enviado, é inválido ou expirou. Gere um novo token — veja [Autenticação](https://documentacao.credicarro.com.br/pages/authentication.md).

> **404 em uma proposta que existe**
>
> A proposta pode pertencer a outro parceiro, ou o token pode ser de outro ambiente (staging x produção).

> **409 Conflict em POST**
>
> Uma `Idempotency-Key` já usada com um corpo diferente. Gere uma nova chave para uma nova operação — veja [Erros e idempotência](https://documentacao.credicarro.com.br/pages/errors.md).

> **404 ou 422 na simulação**
>
> `404` (`Store.Integration.NotFound`): o `cnpjLoja` não existe ou não está vinculado ao seu cadastro de parceiro. `422` (`Store.Integration.Intermediation`): a loja tem contrato de intermediação e não pode ser usada na integração.

## Boas práticas de segurança

> * Armazene `ClientId`/`ClientSecret` em variáveis de ambiente ou um gerenciador de segredos — nunca no código-fonte
> * Nunca exponha o `ClientSecret` em código client-side (app mobile, SPA)
> * A Credicarro nunca solicita suas credenciais por e-mail ou telefone

## Por onde continuar

> **[Fluxo da proposta](https://documentacao.credicarro.com.br/pages/v2/overview.md)**
>
> A ordem de chamadas do início ao fim.

> **[Guia de financiamento](https://documentacao.credicarro.com.br/pages/guides/financing-integration.md)**
>
> Todas as chamadas de um financiamento, com exemplos.

> **[Guia de refinanciamento](https://documentacao.credicarro.com.br/pages/guides/refinancing-integration.md)**
>
> Inclui a conta de recebimento.

> **[Envio de documentos](https://documentacao.credicarro.com.br/pages/guides/document-upload.md)**
>
> Base64, idempotência e correção.

> **[Etapas e status](https://documentacao.credicarro.com.br/pages/v2/steps.md)**
>
> O significado de cada código da proposta.

> **[Webhooks](https://documentacao.credicarro.com.br/pages/webhooks.md)**
>
> Notificações em tempo real sobre a proposta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.