> ## Documentation Index
> Fetch the complete documentation index at: https://developer.noodle.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduçao

> Integração com a API da Noodle

## Para Quem é a API da Noodle?

Nossa API foi desenhada para empresas que buscam automação e controle total sobre seus fluxos de pagamento.

<Cards columns={2}>
  <Card title="🏦 Conta Noodle Ativa" icon="bank">
    Para utilizar a API, é pré-requisito que sua empresa possua uma conta bancária PJ aberta e ativa na Noodle. É através dela que todas as transações serão liquidadas.
  </Card>

  <Card title="🎨 Controle Total da Experiência" icon="palette">
    A Noodle fornece o motor de pagamentos. Toda a interface visual, gestão de usuários e experiência do cliente final é de total responsabilidade da sua aplicação.
  </Card>
</Cards>

## Ciclo de Vida de um Split

Siga estes 4 passos para criar, processar e acompanhar seus pagamentos via API.

1. **Criação do Split**\
   Envie um `POST` para `/external/split`. A API retorna um split com status `PENDING` e um **QR Code Pix** vinculado.

2. **Disparo do Processamento**\
   O processamento pode ser iniciado de duas formas:

* **Pagando o QR Code** gerado.
* Enviando um `POST` para `/external/split/{id}/pay` (requer **senha transacional**).

3. **Acompanhamento**\
   Use `GET /external/split/{id}/get` para consultar o status do split e `GET /external/split/{id}/payments` para ver os detalhes de cada pagamento.

4. **Finalização**\
   Quando todos os pagamentos forem processados, o status final do split será `DONE`. Verifique o campo `errorReason` para falhas.

## Entendendo os Status

Cada split e pagamento possui um status que indica sua posição no fluxo.

### Status do Split

* `PENDING`: Split criado, aguardando ação.
* `PROCESSING`: Pagamentos em execução.
* `DONE`: Todos os pagamentos foram processados.

### Status do Pagamento

* `PENDING`: Aguardando processamento.
* `PAID`: Pagamento concluído com sucesso.
* `ON_HOLD`: Pagamento retido manualmente pelo cliente.
* `ERROR`: Falha no pagamento.

## Visualizando um Split Típico

Após o processamento, um split típico terá a maioria dos pagamentos concluída com sucesso, com uma pequena fração podendo apresentar erros a serem tratados.

A distribuição de status em um Split Finalizado tipicamente mostra 95% de pagamentos como 'Pago com Sucesso', 3% com 'Erro no Pagamento', e 2% 'Retido Manualmente'.

## Endpoints Essenciais

A tabela abaixo resume as operações centrais para sua integração.

| Ação | Método | Endpoint |
| :- | :- | :- |
| Criar Split | `POST` | `/external/split` |
| Pagar Split | `POST` | `/external/split/{id}/pay` |
| Buscar Split | `GET` | `/external/split/{id}/get` |
| Listar Pagamentos do Split | `GET` | `/external/split/{id}/payments` |
| Apagar Split | `DELETE` | `/external/split/{id}` |
| Marcar como Pago | `POST` | `/external/split/payments/{payment_id}/paid` |
| Marcar como Pendente | `POST` | `/external/split/payments/{payment_id}/pending` |
| Reter Pagamento | `POST` | `/external/split/payments/{payment_id}/withhold` |

***

## 🚀 Conceito Principal: Autenticação Segura

Para garantir a máxima segurança, nossa API não usa chaves estáticas. Em vez disso, cada requisição é protegida por uma **assinatura JWT única**, gerada com uma chave privada que só você possui.

<Card title="Entenda a Autenticação" icon="key" href="/authentication">
  Aprenda em detalhes como funciona nosso fluxo de assinatura e por que ele é tão seguro.
</Card>

***

## Primeiros Passos

Navegue pelas seções abaixo para começar a usar a API.

<Card title="Referência Completa da API" icon="code" href="/api-reference/openapi.json">
  Explore todos os endpoints disponíveis, seus parâmetros e respostas esperadas na nossa referência interativa.
</Card>

## Precisa de Ajuda?

Se tiver qualquer dúvida sobre o processo de autenticação ou uso da API, nossa equipe está pronta para ajudar.

<Info>
  **Contato de Suporte:** [api@noodle.cx](mailto:api@noodle.cx)
</Info>


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