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

# Configuração do trilho

> Configure o Pix Direto via JD do zero em um serviço que já está rodando, na ordem em que você age: os pré-requisitos, a assinatura das ordens de pagamento, os registros do ledger Midaz e do CRM, as rotas contábeis, as configurações do plugin, o pagamento que cria as linhas de limite e as verificações que provam que cada passo foi aplicado.

Um deploy novo do Pix Direto via JD sobe, responde à health probe dele e recusa todo pagamento. Nada está quebrado. O trilho precisa de uma cadeia de objetos antes de poder mover dinheiro. Enquanto eles não existem, ele recusa o pagamento e não adivinha.

Esta página mostra essa cadeia como um único roteiro, na ordem em que você age, para um serviço que já está instalado e rodando, com a falha que cada elo ausente causa. A Lerian executa essa configuração com você durante o onboarding. Use a página para saber o que deve existir, o que cada valor significa e como provar que ele foi aplicado.

> [!NOTE]
>
> Na Lerian Cloud, a Lerian roda o serviço. Você entrega à Lerian os valores de assinatura do passo 2, só se a JD os exigir. Todos os outros passos desta página são seus para executar, porque eles criam os seus próprios livros e as suas próprias configurações.

> [!NOTE]
>
> A ordem é uma cadeia de dependências. O Midaz recusa cada elo enquanto o anterior não existe. O passo de limites envia um pagamento, então ele vem depois das configurações. Onde um passo pode rodar em qualquer ordem, a página diz isso.

## O roteiro

1. [Confira os pré-requisitos](#step-1-check-the-prerequisites) e garanta o acesso de quem vai fazer a configuração.
2. [Configure a assinatura das ordens de pagamento](#step-2-set-up-payment-order-signing-if-jd-requires-it), apenas se a JD a exigir para a sua instituição.
3. [Provisione o ledger e os registros de titular](#step-3-provision-the-ledger-and-the-holder-records) no Midaz e no CRM.
4. [Crie as rotas contábeis](#step-4-create-the-accounting-routes) no Midaz.
5. [Configure o trilho](#step-5-configure-the-rail): as configurações do plugin.
6. [Envie o pagamento que cria as linhas de limite](#step-6-create-the-transaction-limit-rows-with-one-small-payment).
7. [Prove que a configuração está completa](#step-7-prove-the-setup-is-complete), até uma chave Pix registrada.
8. [Adicione as capacidades opcionais](#step-8-add-the-optional-capabilities) de que a sua instituição precisa.

## Passo 1: Confira os pré-requisitos

Você usa três endereços. Não os confunda.

| Serviço | Endereço | As rotas começam com | Header extra |
| - | - | - | - |
| Ledger (Midaz) | `MIDAZ_URL_ONBOARDING`, `MIDAZ_URL_TRANSACTION` | `/v1/organizations/...` | — |
| CRM (titulares de conta), dentro do Midaz | `CRM_URL` | `/v2/organizations/.../holders`, `/v2/organizations/.../instruments` | — |
| O plano de administração do plugin | o endereço do próprio plugin | `/system/...` | — |

Você também precisa de:

* O plugin Pix rodando. A API de configurações do plugin precisa estar habilitada (`SYSTEMPLANE_ENABLED=true`). Sem ela, toda chamada de configuração do passo 5 responde `404`. No SaaS, a Lerian a habilita.
* Em um deploy self-hosted em que a [declaração de permissões](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-environment-variables.md#permission-declaration) do Pix JD não está publicada, estas permissões nos papéis do Pix no Access Manager:

  * `entries-lookup` (ação `get`), para a rota de consulta de chave.
  * `parked-credits` (ação `post`), para as [rotas de crédito em espera](https://docs.lerian.studio/pt/interfaces/pix-jd/direct-pix-via-jd.md#received-pix-that-waits-for-an-operator).
  * Com o JD Courier, `courier-ownership` (ação `post`), para a rota de propriedade do Courier.

  Sem a permissão dela, cada rota responde `403`. Depois que a declaração é publicada, os papéis que ela declara têm essas permissões.
* Um bearer token para o Midaz e um para o plugin, emitidos pelo Access Manager. Eles podem vir de audiences diferentes.
* A credencial da JD, quando a JD chama o plugin sem o JD Courier. Veja [Dê à JD a credencial dela](#give-jd-its-credential).
* O acesso certo para quem vai fazer a configuração. O [passo de acesso](#grant-access-to-whoever-runs-the-setup) abaixo lista os grupos. Sem ele, as chamadas respondem `403`.
* O **ISPB** da sua instituição: o identificador do seu credenciamento no BACEN, 8 letras maiúsculas ou dígitos.

Os exemplos abaixo usam estas variáveis de shell. Onde o trilho já tem um nome para um valor, a variável tem esse mesmo nome. Todo UUID, documento e ISPB é um placeholder. Use os valores do seu próprio ambiente.

```bash theme={null}
# Addresses. MIDAZ_URL_TRANSACTION and CRM_URL are this rail's own deployment variables.
MIDAZ_URL_ONBOARDING="https://midaz-onboarding.example.com"
MIDAZ_URL_TRANSACTION="https://midaz-transaction.example.com"
CRM_URL="$MIDAZ_URL_ONBOARDING"                    # Midaz serves the CRM
PIX_JD_BASE_URL="https://pix-jd.example.com"       # this deployment's own address

# Two different bearers. They are not interchangeable.
MIDAZ_BEARER_TOKEN="..."                           # for Midaz and its CRM
PIX_JD_BEARER_TOKEN="..."                          # for the plugin, needs Plugin PIX JD Editor

MIDAZ_HEADERS=(-H "Authorization: Bearer $MIDAZ_BEARER_TOKEN"
               -H 'Content-Type: application/json')
```

> [!NOTE]
>
> O Midaz tem uma superfície de onboarding e uma superfície de transação. Quando um endereço serve as duas, dê o mesmo valor às duas variáveis. As chamadas abaixo seguem o objeto que cada uma cria.

### Garanta o acesso de quem vai fazer a configuração

**Por que este passo existe.** Configurar o Pix mexe em dois produtos: o Midaz, com o cadastro de titulares (CRM), e o próprio plugin Pix JD. Cada um confere a sua própria permissão. Sem ela, a chamada responde `403` e nada é gravado.

**Se você é administrador, já tem tudo.** O grupo **Administrator** (`admin-group`) tem acesso completo aos dois produtos. Siga para o próximo passo.

**Para que outra pessoa faça a configuração sem ser administradora,** coloque essa pessoa nos grupos abaixo pelo Access Manager, no console ou por [Update a User](https://docs.lerian.studio/pt/reference/platform/access-manager/update-user.md). É o acesso mínimo que cobre todos os passos desta página:

| Grupo no console | Identificador na API | Para quê |
| - | - | - |
| **Plugin PIX JD Editor** | `plugin-br-pix-jd-editor-group` | Gravar a configuração do Pix: o vínculo com o seu ISPB, o roteamento, a janela diária e a chave que liga os participantes indiretos. Além dos administradores, é o único grupo que pode alterar essa configuração. |
| **Midaz Editor** | `midaz-editor-group` | Criar a organização, o ledger, o ativo, as contas, os saldos, as rotas contábeis, o titular e o vínculo entre o titular e a conta. Apagar a conta de teste da verificação final. |

**Depois da configuração, reduza o acesso.** Para a operação do dia a dia (pagamentos, limites, participantes indiretos), **Plugin PIX JD Contributor** (`plugin-br-pix-jd-contributor-group`) basta. Ele não altera a configuração do Pix, então um erro de operação não muda o roteamento do seu dinheiro. Para quem só consulta, use **Plugin PIX JD Viewer** (`plugin-br-pix-jd-viewer-group`).

**Prove que o acesso está certo antes de seguir.** Com o token da pessoa:

* `GET /system/-/catalog` deve responder `200`.
* A primeira escrita em `/system`, a do vínculo de integração no passo 5, deve responder `204 No Content`. Um `403` ali significa que a pessoa não está no grupo **Plugin PIX JD Editor**.

```bash theme={null}
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
  "$PIX_JD_BASE_URL/system/-/catalog"
```

### Dê à JD a credencial dela

**Por que este passo existe.** A JD chama o plugin para o Pix recebido e para os fluxos do Pix Automático. Essas rotas aceitam quatro credenciais: a credencial do JD Courier, a aplicação existente da JD com a origem `jd-consultores`, uma aplicação que você lista para a JD, e um parceiro que tem as permissões de canal da JD. Qualquer outro chamador recebe `403 PIX-0005`.

**Atrás do JD Courier, a JD não precisa de credencial sua.** O Courier chama o plugin com a credencial dele. No modo multi-tenant, o Tenant Manager a emite. No modo single-tenant, um administrador a emite com [Emitir uma credencial de serviço](https://docs.lerian.studio/pt/reference/platform/access-manager/issue-a-service-credential.md), com a origem `jd-courier` e o destino `plugin-br-pix-jd`. Essa chamada responde `422` enquanto a declaração de permissões do Pix JD não está publicada.

**Uma aplicação existente com a origem `jd-consultores` continua funcionando.** Você não precisa de mais nada para ela.

**A JD também pode chamar como parceiro do seu tenant.** Veja [A JD como parceiro](https://docs.lerian.studio/pt/platform/access-manager/features/partners/pix-jd.md#jd-as-a-partner).

**Para listar uma aplicação para a JD, sem o JD Courier:**

1. Defina `AUTH_M2M_INVERSION_ENABLED=true` e `AUTH_M2M_PRODUCT_FORWARD_ENABLED=true` no plugin. Defina as duas juntas. Só com a primeira, o plugin recusa o JD Courier com `403`. Na Lerian Cloud, a Lerian as define.
2. No Access Manager, crie uma aplicação com o destino `plugin-br-pix-jd` e sem origem.
3. Escreva o client ID dela na chave do plugin `tenant_policy/jd.direct_client_ids`. Uma pessoa do **Plugin PIX JD Editor**, ou um administrador, precisa fazer a escrita. Um token de aplicação recebe `403`. Um `PUT` substitui a lista inteira, então leia a chave primeiro e envie todo client ID que precisa continuar, separados por vírgulas.
4. Entregue à JD o client ID e o secret.

```bash theme={null}
JD_CLIENT_IDS="<client ID of JD's application>"   # every listed ID, separated by commas

curl -s -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
  "$PIX_JD_BASE_URL/system/tenant_policy/jd.direct_client_ids" | jq

curl -s -o /dev/null -w '%{http_code}\n' -X PUT \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d "$(jq -nc --arg ids "$JD_CLIENT_IDS" '{value:$ids}')" \
  "$PIX_JD_BASE_URL/system/tenant_policy/jd.direct_client_ids"
```

Uma aplicação listada recebe `403 PIX-0005` em toda rota que a JD não chama.

> [!WARNING]
>
> Para cortar a JD, exclua a aplicação dela no Access Manager. Remover o client ID da lista não revoga a aplicação. Ela passa a ter o acesso das suas próprias aplicações, Pix enviado incluído.

## Passo 2: Configure a assinatura das ordens de pagamento, se a JD a exigir

A JD pode exigir uma assinatura em cada ordem de pagamento da sua instituição. Confirme isso com a JD. Se a JD a exigir, siga [Assinatura da ordem de pagamento](https://docs.lerian.studio/pt/interfaces/pix-jd/payment-order-signing.md) agora, antes de qualquer pagamento. Se a JD não a exigir, pule este passo.

> [!WARNING]
>
> Faça este passo antes do passo 6. O passo 6 envia um pagamento. Se a JD exige ordens assinadas e a ordem não está assinada, a JD a recusa. Depois de recusas repetidas, a JD bloqueia todos os débitos da sua instituição.

## Passo 3: Provisione o ledger e os registros de titular

Estes passos rodam contra o Midaz e o CRM dele. Eles criam as contas em que o trilho lança e os registros de titular de onde ele lê as contrapartes.

**Acesso:** **Midaz Editor**.

**1. Crie a organização e o ledger**

A organização é a sua instituição nos livros. O ledger é o livro em que ela lança. Uma instituição pode ter mais de um ledger. Este trilho lança no ledger **padrão**: o par que você cria aqui e nomeia no vínculo do passo 5. Todo fluxo usa esse par até você declarar mais livros no catálogo de organizações. Para o catálogo, veja [Multiorganização e ledgers](https://docs.lerian.studio/pt/interfaces/pix-jd/multi-organization-and-ledgers.md).

```bash theme={null}
curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations" "${MIDAZ_HEADERS[@]}" -d '{
  "legalName": "Example Institution",
  "legalDocument": "12345678000199",
  "address": { "country": "BR" }
}'
# -> {"id": "..."}  keep it as $MIDAZ_ORGANIZATION_ID

curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers" "${MIDAZ_HEADERS[@]}" -d '{
  "name": "Pix ledger"
}'
# -> {"id": "..."}  keep it as $MIDAZ_LEDGER_ID
```

Um `201` sem `id` no corpo não é sucesso. Nada consegue endereçar o novo objeto, nem você nem uma limpeza posterior. Pare aí. Não leve um id vazio para o passo seguinte.

**2. Crie o ativo BRL e espere ele aparecer**

O ativo é a moeda dos registros. Para Pix ele é `BRL`.

```bash theme={null}
curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/assets" "${MIDAZ_HEADERS[@]}" -d '{
  "name": "BRL",
  "type": "currency",
  "code": "BRL"
}'
```

Tanto `201` quanto `409` são boas respostas. Um ledger endereça um ativo pelo código dele, então "já existe" significa o mesmo que sucesso.

Duas coisas acontecem aqui:

1. O ledger começa a aceitar contas naquele ativo. Antes disso, ele recusa toda conta com `0034 Asset Code Not Found`.
2. O Midaz cria a conta **`@external/BRL`** junto com o ativo. Ela é a única conta em um livro que você pode debitar antes de qualquer crédito. O saldo inicial vem dela. Ela também é a contraparte de toda liquidação com o mundo externo.

> [!WARNING]
>
> O `201` chega antes de o ativo aparecer na listagem. Um script que cria o ativo e depois cria uma conta na linha seguinte falha de vez em quando. Faça polling da listagem até o código aparecer, com um prazo:
>
> ```bash theme={null}
> deadline=$(( $(date +%s) + 12 ))
> until curl -s "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/assets" "${MIDAZ_HEADERS[@]}" \
>       | jq -e '.items[]? | select(.code=="BRL")' >/dev/null; do
>   if [ "$(date +%s)" -ge "$deadline" ]; then
>     echo "aborted: BRL did not appear in the listing within 12s" >&2
>     echo "do not create the account: it would be refused with 0034" >&2
>     exit 1
>   fi
>   sleep 0.15
> done
> ```

**3. Crie uma conta por papel**

Crie uma conta para cada papel que o seu ambiente usa: pagador, recebedor e os outros papéis do seu produto.

```bash theme={null}
curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts" "${MIDAZ_HEADERS[@]}" -d '{
  "name": "payer account",
  "assetCode": "BRL",
  "type": "deposit",
  "alias": "@payer",
  "status": { "code": "ACTIVE" }
}'
# -> {"id": "..."}  keep it as $MIDAZ_ACCOUNT_ID
```

Você usa o id da conta duas vezes mais adiante: no vínculo do CRM abaixo e como o `accountId` das chamadas de negócio que você faz ao plugin. O **alias** (`@payer`) é o nome curto pelo qual o livro lê e lança. Ele volta no passo seguinte.

**4. Crie o titular no CRM**

O titular é o dono da conta. O plugin lê **quem** é uma contraparte no CRM, não no ledger.

```bash theme={null}
curl -s -X POST "$CRM_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/holders" \
  "${MIDAZ_HEADERS[@]}" -d '{
  "type": "NATURAL_PERSON",
  "document": "12345678909",
  "name": "Example Person",
  "externalId": "@payer",
  "addresses": { "primary": { "city": "SAO PAULO" } }
}'
# -> {"id": "..."}  keep it as $CRM_HOLDER_ID
```

Quatro campos exigem cuidado:

* **`document` deve ser um CPF ou CNPJ válido, com os dígitos verificadores corretos.**
* **`type` segue o tamanho do documento.** Use `NATURAL_PERSON` para um CPF (11 dígitos) e `LEGAL_PERSON` para um CNPJ (14). O plugin converte esse tipo no número que vai para a JD. Um tipo errado registra a parte como o tipo errado de pessoa.
* **`externalId` guarda o alias da conta no ledger** (`@payer`). O CRM o chama de identificador externo de correlação, então ele parece opcional. Para este trilho não é. Um registro de chave Pix para um titular sem `externalId` responde `422 PIX-0108`.
* **`addresses.primary.city` é obrigatório para QR codes e Pix Automático.** É a cidade do recebedor no código. Sem ela, o plugin se recusa a gerar um QR e responde `422 PIX-0033` para `payee.city`. Nenhum caminho de pagamento lê o campo, então a ausência dele aparece apenas quando alguém gera um QR.

**5. Vincule o titular à conta**

O titular e a conta no ledger existem, mas nada os une ainda. Este passo é a união, que o CRM chama de **instrumento**. O plugin a usa para descobrir **onde creditar** um Pix recebido e qual conta um pagamento debita.

```bash theme={null}
curl -s -X POST "$CRM_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/holders/$CRM_HOLDER_ID/instruments" \
  "${MIDAZ_HEADERS[@]}" -d '{
  "ledgerId":  "'"$MIDAZ_LEDGER_ID"'",
  "accountId": "'"$MIDAZ_ACCOUNT_ID"'",
  "bankingDetails": {
    "branch":      "0001",
    "account":     "12345675",
    "type":        "CACC",
    "openingDate": "2020-01-02",
    "bankId":      "12345678"
  }
}'
```

| Campo | O que é | Se estiver ausente |
| - | - | - |
| `ledgerId`, `accountId` | o livro e a conta dos passos anteriores | o vínculo não endereça nada |
| `branch`, `account` | agência e conta, as coordenadas que resolvem um Pix recebido. O `account` guarda o número e o dígito juntos, sem separador: a conta 1234567-5 fica `12345675`. Um [Pix para um recebedor da sua instituição](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/create-transaction.md) junta `accountNumber` e `accountDigit` e procura exatamente esse valor | o crédito não encontra destino, e o Pix para a sua instituição responde `404 PIX-2016` |
| `type` | `CACC` corrente, `SLRY` salário, `SVGS` poupança, `TRAN` pagamento | `400 PIX-0061` nas operações de chave Pix, porque o tipo de conta Pix é desconhecido |
| `openingDate` | a **data** de abertura da conta, não um instante | `400 PIX-0061`, que diz que a data de abertura é desconhecida, no registro de chave e na abertura de reivindicação |
| `bankId` | o ISPB da sua própria instituição | veja o aviso abaixo |

> [!WARNING]
>
> Nunca envie `bankId` como string vazia. Uma string vazia é um valor. Ela registra "esta conta pertence à instituição cujo ISPB é vazio", o que é pior do que nenhum valor. Se você ainda não tem o ISPB, omita o campo.

Confira o que o CRM registrou, e sempre filtre. Uma consulta sem filtro retorna o primeiro vínculo da organização. É assim que uma verificação pode aprovar a conta de outra pessoa:

```bash theme={null}
curl -s -G "$CRM_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/instruments" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  --data-urlencode 'document=12345678909' \
  --data-urlencode 'banking_details_branch=0001' \
  --data-urlencode 'banking_details_account=12345675' | jq
```

**6. Coloque saldo nas contas**

Uma conta nova tem zero, e você não pode pagar a partir de uma conta vazia. O crédito inicial vem de `@external/BRL`, que o Midaz criou junto com o ativo, dois passos acima.

> [!NOTE]
>
> Em produção, você não coloca saldo assim na conta de cliente de um participante direto. O dinheiro entra como um Pix real recebido, ou como um aporte que o cliente faz. A carga via `@external/BRL` tem dois usos. Um é a posição de liquidação `@pi` de um participante indireto hospedado. O outro é um ambiente de teste ou homologação, onde nenhum Pix real chega. Veja [O modelo direto e indireto](https://docs.lerian.studio/pt/interfaces/pix-jd/direct-and-indirect-model.md) para saber o que cada posição é.

```bash theme={null}
curl -s -X POST "$MIDAZ_URL_TRANSACTION/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/transactions/json" "${MIDAZ_HEADERS[@]}" -d '{
  "description": "opening balance",
  "send": {
    "asset": "BRL",
    "value": "100.00",
    "source":     { "from": [ { "accountAlias": "@external/BRL",
                                "amount": { "asset": "BRL", "value": "100.00" } } ] },
    "distribute": { "to":   [ { "accountAlias": "@payer",
                                "amount": { "asset": "BRL", "value": "100.00" } } ] }
  }
}'
```

> [!WARNING]
>
> Dois corpos idênticos enviados em até 300 segundos fazem um lançamento só. O Midaz colapsa a repetição: o segundo `POST` responde `201` com o id do primeiro lançamento, e nada se move. Use essa propriedade quando fizer uma **nova tentativa**.
>
> A nova tentativa de uma recarga cuja resposta você perdeu deve enviar o **corpo exatamente igual**, `description` incluído, em até 300 segundos. Assim a conta não pode receber dois créditos. Depois dessa janela, leia o saldo da conta antes de enviar a recarga de novo. Mude o `description` apenas para uma recarga **nova**. Uma nova `description` em uma nova tentativa real adiciona um segundo crédito por engano.

Você pode nomear `@external/BRL` em um corpo, mas não em um caminho. O alias contém uma barra, e a rota do ledger não a decodifica. Uma leitura de saldo por caminho responde `404` ou um `200` vazio. Lançar a partir dela é normal. Lê-la desse jeito não é.

## Passo 4: Crie as rotas contábeis

Cada caminho de dinheiro neste trilho tem o próprio par de rotas de operação do Midaz: uma perna de crédito e uma perna de débito. O passo 5 guarda os UUIDs das rotas no plugin.

**Acesso:** **Midaz Editor**.

**Quais pares você precisa.** Você não cria um par para cada perfil. Crie um par para cada um dos seis perfis de pagamento. Os outros perfis reutilizam um par, ou ficam vazios:

| Perfil | Quando o trilho o usa | Par |
| - | - | - |
| `in` | um crédito recebido | par próprio. Obrigatório |
| `out` | um pagamento enviado | par próprio. Obrigatório |
| `out_reversal` | um pagamento que você enviou e que volta | par próprio. Obrigatório |
| `in_qrcode` | um crédito recebido por um QR code | par próprio. Obrigatório |
| `intra_psp` | um pagamento entre duas contas da sua própria instituição | par próprio. Obrigatório |
| `intra_psp_reversal` | o estorno desse pagamento | par próprio. Obrigatório |
| `med_credit` | a perna de crédito de uma devolução de MED (fraude) | apenas se você usa MED. Reutilize o par de `in` |
| `med_debit` | a perna de débito de uma devolução de MED (fraude) | apenas se você usa MED. Reutilize o par de `out` |
| `pixautomatico_debit` | o débito do Pix Automático | apenas se você usa Pix Automático. Reutilize o par de `out` |
| `pixautomatico_reversal` | o estorno do Pix Automático | apenas se você usa Pix Automático. Reutilize o par de `in` |
| `refund_sent` | uma devolução que você envia pelo SPI | opcional. Enquanto as duas pernas estão vazias, o trilho a lança nas rotas de `out` |

Então o mínimo são seis pares, doze rotas. Um perfil pode reutilizar o par de outro perfil apenas quando o dinheiro se move na mesma direção. Uma devolução de MED e um estorno do Pix Automático trazem dinheiro, como `in`. Um débito de MED e um débito do Pix Automático tiram dinheiro, como `out`.

Crie cada perna com uma chamada:

```bash theme={null}
# a CREDIT leg -> operationType "destination" (money ARRIVES)
curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/operation-routes" "${MIDAZ_HEADERS[@]}" -d '{
  "title": "pix-jd out credit",
  "description": "Pix JD accounting route",
  "operationType": "destination"
}'

# a DEBIT leg -> operationType "source" (money LEAVES)
curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/operation-routes" "${MIDAZ_HEADERS[@]}" -d '{
  "title": "pix-jd out debit",
  "description": "Pix JD accounting route",
  "operationType": "source"
}'
```

Cada chamada retorna `{"id": "..."}`. Guarde cada id com o perfil e a perna dele. O passo 5 os escreve.

> [!WARNING]
>
> Você pode inverter a direção, e nada avisa você. Um débito **sai** do pagador, então é a perna `source`. Um crédito **chega**, então é a perna `destination`. Se você trocá-las, todo lançamento continua respondendo sucesso, na direção errada. Nenhum código de status relata isso.

Procure uma rota pelo título antes de criá-la. Com duas rotas do mesmo título, a busca seguinte pode escolher qualquer uma das duas. Se você provisiona o mesmo livro mais de uma vez, liste primeiro.

Se o seu ledger valida rotas, crie também uma rota de transação do Midaz por perfil que você usa. Um ledger que valida rotas recusa um lançamento que não nomeia nenhuma rota de transação. Veja [Entidades de roteamento de transações](https://docs.lerian.studio/pt/products/midaz/transaction-routing-entities.md) para saber como criar uma.

## Passo 5: Configure o trilho

O plugin guarda a configuração viva dele no **systemplane** dele. Você escreve esses valores pela API de administração, e eles passam a valer sem um novo deploy e sem um reinício. Toda escrita é um `PUT` para `/system/<namespace>/<key>` com um corpo `{"value": ...}`. Um sucesso responde `204 No Content`, sem corpo.

O tenant vem do bearer validado, nunca da URL nem do corpo.

**Acesso:** toda escrita abaixo exige **Plugin PIX JD Editor**. Esses valores decidem com qual instituição o plugin se apresenta à JD e em quais contas ele lança, então apenas esse grupo e os administradores podem alterá-los. Qualquer grupo do Pix JD pode lê-los.

> [!NOTE]
>
> Pergunte ao plugin o que ele espera. Não confie em uma cópia. `GET /system/-/catalog` lista cada chave com o tipo e a descrição dela, e `GET /system/-/catalog/<namespace>/<key>` descreve uma chave. O catálogo é a fonte da verdade. Esta página é uma cópia dele, e cópias envelhecem.

**1. Escreva o vínculo de integração com a JD**

**O que é.** O vínculo é um documento com três campos. O ISPB é o código de 8 caracteres, letras maiúsculas ou dígitos, que identifica a sua instituição no Banco Central. Ele vai em toda mensagem de Pix, e o plugin não consegue assinar como a sua instituição sem ele. Os outros dois campos nomeiam a sua organização e o seu ledger **padrão** do Midaz, do passo 3.

**Onde fica.** Nenhum dos três é uma variável de deploy. Eles vêm da chave de systemplane `tenancy/jd_integration_binding`, sem fallback por ambiente. Enquanto a chave está vazia, o plugin sobe e responde à health probe dele. Ele recusa **todo** pagamento em **toda** rota de dinheiro.

**O que quebra sem ele.** `409 PIX-0092`, *"Tenant Pix integration not provisioned"*. O texto da resposta pede que você contate o suporte e não nomeia a chave. Procure pelo código.

> [!WARNING]
>
> Reiniciar não ajuda. O plugin lê a chave em cada chamada, não no boot. Um deploy sem ISPB continua sem ISPB depois de um reinício. Escreva a chave com a aplicação rodando, e a requisição seguinte passa, sem um novo deploy.

**O valor é um documento JSON dentro de uma string.** O corpo é sempre `{"value": ...}`. Aqui `value` não é um objeto. É uma **string**, e o conteúdo dela é um documento JSON. O plugin o armazena com as aspas internas escapadas:

```text theme={null}
"{\"ispb\":\"12345678\",\"organizationId\":\"...\",\"ledgerId\":\"...\"}"
```

| Forma | Resultado |
| - | - |
| `{"value":"{\"ispb\":\"12345678\",...}"}`, uma string | correto |
| `{"value":{"ispb":"12345678",...}}`, um objeto | recusado |

Deixe o `jq` fazer o escaping:

```bash theme={null}
# Replace all three with your own values before you run this.
INSTITUTION_ISPB="12345678"                                    # 8 uppercase letters or digits, your institution's ISPB
MIDAZ_ORGANIZATION_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"   # the organization from step 3
MIDAZ_LEDGER_ID="9c858901-8a57-4791-81fe-4a34d4dd8ab5"         # the ledger from step 3

# 1) build the document
BINDING_DOCUMENT="$(jq -nc \
        --arg ispb   "$INSTITUTION_ISPB" \
        --arg orgId  "$MIDAZ_ORGANIZATION_ID" \
        --arg ledgerId "$MIDAZ_LEDGER_ID" \
        '{ispb:$ispb, organizationId:$orgId, ledgerId:$ledgerId}')"

# 2) wrap the document as a STRING inside {"value": ...} and write it
curl -s -o /dev/null -w '%{http_code}\n' -X PUT \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d "$(jq -nc --arg document "$BINDING_DOCUMENT" '{value:$document}')" \
  "$PIX_JD_BASE_URL/system/tenancy/jd_integration_binding"
```

| Campo | Regra | Obrigatório na escrita | Lido em tempo de execução |
| - | - | - | - |
| `ispb` | exatamente 8 letras maiúsculas ou dígitos, sem máscara e sem espaços | sim | sim, em cada chamada |
| `organizationId` | um UUID válido e diferente de zero (o plugin recusa o UUID só de zeros) | sim | sim, em cada chamada |
| `ledgerId` | um UUID válido e diferente de zero | sim | sim, em cada chamada |

> [!NOTE]
>
> O vínculo nomeia a sua organização e o seu ledger **padrão**. Todo fluxo lança nesse par, a menos que resolva outro pelo [catálogo de organizações](https://docs.lerian.studio/pt/interfaces/pix-jd/multi-organization-and-ledgers.md). Se `organizationId` ou `ledgerId` está ausente ou inutilizável, o plugin recusa todo lançamento, devolução e crédito de entrada com `409 PIX-0106`.

> [!WARNING]
>
> O decodificador é estrito. Ele recusa um campo desconhecido, e essa recusa interrompe a escrita inteira. Isso inclui o campo antigo `routeProfiles`, porque as rotas contábeis foram para as chaves `routing.*` abaixo. Por isso, um documento de uma configuração antiga falha. O decodificador também recusa qualquer coisa depois do primeiro documento JSON.

**Como conferir.** Leia a chave de volta. Ela não guarda segredo, então o valor volta aberto:

```bash theme={null}
curl -s -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
  "$PIX_JD_BASE_URL/system/tenancy/jd_integration_binding" | jq
```

```json theme={null}
{
  "namespace": "tenancy",
  "key": "jd_integration_binding",
  "value": "{\"ispb\":\"12345678\",\"organizationId\":\"...\",\"ledgerId\":\"...\"}"
}
```

Se `value` volta como um objeto e não como uma string entre aspas, você escreveu a forma errada. Se volta `""`, a escrita não aconteceu. Confira o código de status do `PUT`. A prova real é que as rotas de dinheiro param de responder `409 PIX-0092`.

Você não consegue armazenar um ISPB malformado por esta rota. O validador de escrita usa o mesmo decodificador que a leitura. Ele recusa na hora um ISPB de 7 dígitos ou um UUID quebrado, com `400 validation_error`. Você não descobre o erro no primeiro pagamento.

> [!NOTE]
>
> Por isso, você não vê `409 PIX-0121`, *"Tenant Pix integration ISPB invalid"*, quando segue esta página. Esse código significa que o vínculo existe e o `ispb` dele não tem 8 letras maiúsculas ou dígitos, e esta rota não consegue criar esse estado. Ele aparece apenas quando um valor chegou à chave por outro caminho. Exemplos são uma escrita direta no banco de dados do plugin, ou uma escrita de antes do validador. A mensagem dele nomeia tanto a chave quanto o campo a corrigir.

> [!WARNING]
>
> Um `400` aqui não é um problema de permissão. Uma permissão ausente responde `403`. Este `400` significa que o valor está errado. A resposta não diz qual campo, então confira o ISPB primeiro. Esse é o erro mais comum.

| Resposta | O que significa |
| - | - |
| `204` | escrito |
| `400 validation_error` | o plugin recusou o formato do **valor**. Não é um problema de permissão |
| `400 unknown_key` | o nome da chave ou do namespace está errado |
| `401` | o bearer não autenticou |
| `403` | autenticado, mas sem `systemplane:write`. Coloque a pessoa no grupo **Plugin PIX JD Editor** |
| `404` | o grupo `/system` não está montado, porque `SYSTEMPLANE_ENABLED` é falso |
| `503` | o plano de configuração está indisponível |

O plugin aceita a string vazia, que significa "não provisionado". Se você a escrever, o deploy volta a `409 PIX-0092`. Não faça isso em um ambiente que paga.

**2. Confira a conexão com a JD**

**Por que este passo existe.** O vínculo é a última peça de que o plugin precisa para falar com a JD como a sua instituição. Antes de mover qualquer dinheiro, prove que a conversa funciona: peça à JD a lista de participantes do Pix.

**Acesso:** qualquer grupo do Pix JD, inclusive **Plugin PIX JD Viewer**.

```bash theme={null}
curl -s -w '\n%{http_code}\n' \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
  "$PIX_JD_BASE_URL/v1/banks"
```

O plugin consulta a JD a cada chamada, sem cache, então a resposta é atual. [List Pix participant bank IDs](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/list-pix-participant-bank-ids.md) descreve a resposta.

Uma resposta `200` com a lista de participantes, como esta (resumida), prova que o plugin chegou à JD e recebeu o catálogo de participantes:

```json theme={null}
{
  "data": [
    { "ispb": "00000000", "name": "BCO DO BRASIL S.A." },
    { "ispb": "00360305", "name": "CAIXA ECONOMICA FEDERAL" }
  ]
}
```

Se a resposta for diferente, refaça os passos anteriores, começando pelo acesso e pelo vínculo de integração. Se a resposta continuar diferente, entre em contato com o nosso time de suporte.

**3. Escreva as chaves de roteamento**

**O que é.** Para cada perfil, o par de UUIDs das rotas de operação do Midaz do passo 4. Todas as chaves ficam no namespace `tenant_policy`. Cada uma guarda uma string: o UUID de uma rota que existe no Midaz.

```
tenant_policy/routing.<profile>.operation_credit_route
tenant_policy/routing.<profile>.operation_debit_route
```

**O que quebra sem elas.** O trilho lê os seis perfis de pagamento juntos em cada pagamento. Uma perna ausente de qualquer um dos seis recusa **todo** fluxo de pagamento com `409 PIX-0105`: enviado, recebido, QR code e entre as suas próprias contas. Uma perna ausente de MED ou do Pix Automático recusa apenas aquele fluxo. A exceção é `refund_sent`. Enquanto as duas pernas dele estiverem vazias, o trilho lança uma devolução que você envia nas rotas de `out`.

```bash theme={null}
# OPERATION_ROUTES is the table YOU fill with the UUIDs that step 4 returned:
# one line per profile and leg, "<profile> <leg> <operation route UUID>".
# The six payment profiles have their own pair. MED and Pix Automatico reuse
# the pair of "in" or "out". refund_sent stays empty and posts on "out".
OPERATION_ROUTES="
in                     credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a01
in                     debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a02
out                    credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a03
out                    debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a04
out_reversal           credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a05
out_reversal           debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a06
in_qrcode              credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a07
in_qrcode              debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a08
intra_psp              credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a09
intra_psp              debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a10
intra_psp_reversal     credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a11
intra_psp_reversal     debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a12
med_credit             credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a01
med_credit             debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a02
med_debit              credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a03
med_debit              debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a04
pixautomatico_debit    credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a03
pixautomatico_debit    debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a04
pixautomatico_reversal credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a01
pixautomatico_reversal debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a02
"

operation_route_id() {
  printf '%s\n' "$OPERATION_ROUTES" | awk -v profile="$1" -v leg="$2" \
    '$1 == profile && $2 == leg { print $3 }'
}

for profile in in out out_reversal in_qrcode intra_psp intra_psp_reversal \
               med_credit med_debit pixautomatico_debit pixautomatico_reversal; do
  for leg in credit debit; do
    uuid="$(operation_route_id "$profile" "$leg")"
    if [ -z "$uuid" ]; then
      echo "MISSING the UUID for $profile.$leg — if $profile is one of the six payment profiles, every payment flow refuses with PIX-0105; otherwise only this flow does" >&2
      continue
    fi
    curl -s -o /dev/null -w "$profile/$leg -> %{http_code}\n" -X PUT \
      -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
      -d "{\"value\":\"$uuid\"}" \
      "$PIX_JD_BASE_URL/system/tenant_policy/routing.$profile.operation_${leg}_route"
  done
done
```

**Como conferir.** Cada escrita responde `204`. Se você não usa MED ou Pix Automático, deixe os perfis deles vazios. Esse fluxo então recusa, o que é melhor do que um lançamento em uma rota indefinida.

**A rota de transação de cada perfil.** Cada perfil também tem uma chave opcional, `tenant_policy/routing.<profile>.transaction_route`. Preencha-a quando o seu ledger valida rotas. O plugin então nomeia essa rota de transação em cada lançamento do perfil. Sem ela, esse ledger recusa o lançamento, e o plugin responde `PIX-4011`. Quando o seu ledger não valida rotas, deixe essas chaves vazias.

```bash theme={null}
curl -s -o /dev/null -w '%{http_code}\n' -X PUT \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"value":"2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"}' \
  "$PIX_JD_BASE_URL/system/tenant_policy/routing.out.transaction_route"
```

> [!WARNING]
>
> A string vazia significa "ainda não provisionado", e o plugin a aceita. O plugin recusa o UUID só de zeros. Esse UUID tem um formato válido, mas nunca é um identificador real do Midaz. Não preencha as rotas não usadas com zeros como um "vazio seguro". Use a string vazia.

**4. Defina o ativo de lançamento e a conta de compensação**

**O que é.** O ativo de todo lançamento e a conta externa que representa o mundo fora da sua instituição. Duas chaves de systemplane no namespace `tenant_policy` guardam esses valores, nos dois modos de deploy:

| Chave | O que escrever |
| - | - |
| `tenant_policy/midaz.asset_id` | o **código** do ativo: `BRL` |
| `tenant_policy/midaz.external_id` | o **alias** da conta de compensação: `@external/BRL` |

Os dois valores são strings simples:

```bash theme={null}
PUT() { curl -s -o /dev/null -w "$1 -> %{http_code}\n" -X PUT \
          -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
          -d "$2" "$PIX_JD_BASE_URL/system/$1"; }

PUT tenant_policy/midaz.asset_id    '{"value":"BRL"}'
PUT tenant_policy/midaz.external_id '{"value":"@external/BRL"}'
```

> [!WARNING]
>
> Escreva o código e o alias, não os UUIDs do Midaz do ativo e da conta. Os nomes das chaves terminam em `_id`, mas o plugin coloca o valor no lançamento como ele está.

**O que quebra sem isso.** As duas chaves começam vazias. Até você escrever as duas, o plugin recusa todo lançamento, devolução e crédito de entrada com `409 PIX-0106`, *"Tenant ledger configuration missing"*. A resposta nomeia os campos do vínculo e as duas chaves. Esse código não é `PIX-0105`. Um tenant pode ter todas as pernas de rota e ainda recusar todo lançamento, porque o ativo ou a conta de compensação está vazio.

As variáveis de deploy `MIDAZ_ASSET_ID` e `MIDAZ_EXTERNAL_ID` não existem mais. O plugin as ignora.

**5. Defina a janela diária**

Estas são as duas pontas da janela dos limites de transação. As duas são inteiros de 0 a 23. São horas do relógio, não timestamps. As duas são chaves de systemplane nos **dois** modos de deploy.

```bash theme={null}
PUT tenant_policy/transaction_limits.daily_period_init '{"value":6}'
PUT tenant_policy/transaction_limits.daily_period_end  '{"value":20}'
```

**Por que este passo existe.** Cada instituição escolhe a hora em que a janela diária de limites de transação abre e fecha. O plugin não tem como adivinhar.

Os valores acima são um exemplo. Use os seus. O tipo JSON continua o mesmo: um inteiro, sem aspas. Um valor fora da faixa responde `400`. O plugin não o ajusta ao limite.

**6. Declare se este deploy hospeda participantes indiretos**

`plugin-br-pix-jd.indirects/enabled` declara o que o tenant **é**. Um participante direto simples define o valor como `false`.

```bash theme={null}
curl -s -o /dev/null -w '%{http_code}\n' -X PUT \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"value":false}' \
  "$PIX_JD_BASE_URL/system/plugin-br-pix-jd.indirects/enabled"
```

Esta é uma escrita de configuração, então exige **Plugin PIX JD Editor**. O valor é um booleano JSON, sem aspas. `{"value":"true"}` responde `400`. Se este deploy liquida Pix para outras instituições, o passo 8 define o valor como `true`.

## Passo 6: Crie as linhas de limite de transação com um pagamento pequeno

O produto não tem rota para criar o que este passo precisa.

**O que você espera.** Você provisiona uma conta e lê o limite disponível dela.

**O que acontece.** `GET /v1/limits/available` responde `404 PIX-0063`, *"The specified transaction limit was not found in the system. Please verify the identifier and try again."* `GET /v1/limits` responde `{"data":[]}`. A conta parece quebrada, mas não está. Este é o estado inicial normal de uma conta que nunca enviou um pagamento.

`PIX-0063` nomeia o que o plugin consultou. A [lista de erros](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/pix-jd-error-list.md) mostra a forma genérica dele, *"The specified entity was not found in the system"*. Esta rota coloca `transaction limit` nela. O código e o `404` continuam os mesmos.

**Por que você não pode criar as linhas.** Não existe rota de criação. `PATCH /v1/limits` atualiza linhas que já existem. Apenas a verificação de limite de um pagamento **de saída** cria as linhas. Quando uma conta envia o primeiro pagamento, o plugin não encontra linhas. Ele cria os padrões, lê de novo e continua.

**Então envie um pagamento pequeno de saída.** Um centavo basta.

> [!WARNING]
>
> Se a JD exige ordens de pagamento assinadas para a sua instituição, termine o [passo 2](#step-2-set-up-payment-order-signing-if-jd-requires-it) primeiro. Caso contrário, a JD recusa este pagamento. Depois de recusas repetidas, a JD bloqueia todos os débitos da sua instituição.

**Acesso:** o pagamento exige **Plugin PIX JD Contributor** ou **Plugin PIX JD Editor**. Alterar um limite depois com `PATCH /v1/limits` exige o mesmo.

> [!WARNING]
>
> Uma conta sem linhas de limite não é uma conta sem limite. Se o plugin não consegue criar os limites, ele **recusa** o pagamento.
>
> Não tente forçar as linhas com um valor acima do teto. A verificação de **saldo** roda antes da verificação de limite. Um valor alto falha por falta de fundos antes da verificação de limite, e nenhuma linha aparece. Envie um pagamento comum que cabe no saldo.

**Como conferir.** `GET /v1/limits` muda de `{"data":[]}` para uma lista. `/v1/limits/available` muda de `404` para `200`.

Faça este passo depois de todos os passos acima. O pagamento deve ser lançado, então ele precisa de todos os valores dos passos 3 a 5. Sem uma rota, por exemplo, ele falha com `PIX-0105`.

## Passo 7: Prove que a configuração está completa

Rode estas verificações em ordem. Cada uma falha por um motivo diferente. Isso torna a sequência mais útil do que um único teste de fumaça.

1. **O ledger aceita uma conta.** Crie uma conta descartável e apague-a. Se o livro recusar, a recusa nomeia o elo ausente. Sem esta verificação, o mesmo problema volta depois como "conta não encontrada" dentro de um fluxo de pagamento, a três camadas da causa. Não coloque saldo na conta de teste: o Midaz se recusa a apagar uma conta com saldo. Apagar exige **Midaz Editor**.
2. **O vínculo volta na leitura como uma string entre aspas** com o seu ISPB, a sua organização e o seu ledger, como mostrado no passo 5.
3. **`GET /v1/banks` responde `200`** com a lista de participantes do Pix, como na verificação de conexão do passo 5.
4. **As duas chaves `tenant_policy/midaz.*` voltam na leitura** com o código do ativo e o alias da conta de compensação.
5. **A consulta de instrumentos retorna a sua conta**, filtrada por documento, agência e número da conta.
6. **Uma rota de dinheiro para de responder `409 PIX-0092` e `409 PIX-0106`.** Use a chamada que você já faz. Você não precisa de nenhum aparato de teste.
7. **`GET /v1/limits` retorna uma lista** para a conta que enviou o pagamento do passo 6.
8. **Uma chave Pix é registrada e aparece na lista da conta.** Esta verificação passa pelo CRM, pelo vínculo e pelo DICT na JD.

Para a última verificação, registre uma chave aleatória para a conta. Envie `keyType` `4` e nenhuma `key`: o DICT cria o valor da chave. Uma chave aleatória não precisa de código de confirmação, então ela vai para o DICT na primeira chamada. Ela precisa do header `X-Idempotency`, um texto de no máximo 255 bytes. Um reenvio com o mesmo valor retorna a chave que o DICT já criou:

```bash theme={null}
curl -s -X POST "$PIX_JD_BASE_URL/v1/entries" \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -H "X-Idempotency: setup-check-random-key-1" \
  -d '{"keyType":4,"accountId":"'"$MIDAZ_ACCOUNT_ID"'"}'
```

Depois liste as chaves da conta:

```bash theme={null}
curl -s -G "$PIX_JD_BASE_URL/v1/entries" \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
  --data-urlencode "account_id=$MIDAZ_ACCOUNT_ID" | jq
```

A chave está na lista. Uma chave de CPF ou CNPJ também vai para o DICT na primeira chamada. Uma chave de e-mail ou de telefone também precisa do código de 6 dígitos que o plugin envia pelo provedor de notificação de [Variáveis de ambiente](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-environment-variables.md#notifications). [Register a Pix key entry](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/create-key.md) descreve cada resposta. Quando terminar, remova uma chave de teste com `DELETE /v1/entries/{entryId}`.

## Passo 8: Adicione as capacidades opcionais

A sua configuração termina no passo 7 se a sua instituição é um participante direto com um livro, e liquida apenas o Pix dos próprios clientes. Caso contrário, continue na página que se aplica:

* **Vários livros, ou vários participantes diretos em um deploy.** Siga [Multiorganização e ledgers](https://docs.lerian.studio/pt/interfaces/pix-jd/multi-organization-and-ledgers.md).
* **Liquidar Pix para outras instituições.** Siga [Hospedagem de participantes indiretos](https://docs.lerian.studio/pt/interfaces/pix-jd/hosting-indirect-participants.md). Ela adiciona a chave de criptografia, a postura de hospedagem, o registro de cada participante indireto, o certificado de QR próprio dele se ele tiver um, e o saldo da posição de liquidação dele.

## Como é cada passo pulado

Toda recusa abaixo é um `409`, menos a de limites. Nenhuma delas se resolve se você esperar. Cada uma se resolve quando você provisiona o valor ausente.

| Ausente | Resposta | O que você vê |
| - | - | - |
| o vínculo | `409 PIX-0092` | toda rota de dinheiro recusa. O texto pede que você contate o suporte e não nomeia nenhuma chave |
| uma perna de um dos seis perfis de pagamento | `409 PIX-0105` | todo fluxo de pagamento recusa |
| uma perna de MED ou do Pix Automático | `409 PIX-0105` | apenas aquele fluxo recusa. Os outros continuam funcionando |
| o ativo de lançamento ou a conta de compensação | `409 PIX-0106` | todo lançamento recusa, e a resposta nomeia os valores a definir |
| as linhas de limite de transação | `404 PIX-0063` | *"The specified transaction limit was not found in the system. Please verify the identifier and try again."* |
| a chave de criptografia de entrega (apenas no fluxo indireto) | `409 PIX-0107` | todo registro indireto recusa, e nada é armazenado |

> [!NOTE]
>
> Quando o `PIX-0092` para, os pagamentos nem sempre passam. Ele é apenas a primeira barreira. Com o vínculo no lugar, uma rota contábil vazia ainda responde `PIX-0105`. Um ativo ou uma conta de compensação ausente ainda responde `PIX-0106`. Três códigos têm três causas e três correções diferentes.

### Não repita um `409`. Repita o irmão `503` dele

O status diz se o problema é a sua configuração ou uma indisponibilidade.

Um `409` acima é **conhecimento positivo de ausência**. O trilho leu a sua configuração e não encontrou nada ali. Apenas um operador pode fornecer o valor, então repetir a requisição traz a mesma resposta. Um cliente que faz novas tentativas com este código entra em loop para sempre. Cada uma dessas respostas nomeia o que definir.

A maior parte dessas condições tem um **irmão `503`**. Ele vale quando o trilho não conseguiu ler a configuração de forma alguma. O trilho não sabe nada sobre o que você provisionou. A resposta nomeia a dependência que falhou, e uma nova tentativa é a ação certa.

| A sua configuração está incompleta. Provisione, não repita | A fonte não respondeu. Repita |
| - | - |
| `409 PIX-0092` a integração Pix do tenant não está provisionada | `503 PIX-0051` a integração Pix do tenant não pôde ser alcançada |
| `409 PIX-0121` o vínculo existe e o `ispb` dele não tem 8 letras maiúsculas ou dígitos | `503 PIX-0051` (o mesmo irmão: o vínculo não pôde ser lido) |
| `409 PIX-0106` o ativo de lançamento ou a conta de compensação não está provisionado | `503 PIX-0122` uma parte da configuração do tenant não pôde ser lida |
| `409 PIX-0107` a chave de criptografia do segredo de entrega não está provisionada | `503 PIX-0123` a chave não pôde ser lida da fonte de chaves dela |

> [!WARNING]
>
> **As rotas contábeis são a exceção.** `PIX-0105` não tem irmão `503`. Uma perna de rota ausente, vazia, malformada, o UUID só de zeros **ou ilegível** dá o mesmo `409`. Então um `PIX-0105` sozinho não separa "esta perna não tem valor" de "o plano de configuração não respondeu". Leia as pernas de volta antes de decidir que é uma indisponibilidade.

> [!NOTE]
>
> Os dois códigos de cada par recusam a operação. Nenhum deles lança nem armazena nada. A diferença é apenas a sua próxima ação, por isso eles são códigos separados.
>
> `PIX-0121` é um caso especial. Você não consegue provocá-lo pela API de administração, porque o validador de escrita recusa um `ispb` malformado antes de ele ser armazenado. Ele aparece apenas quando um valor chegou à chave por outro caminho. Veja o vínculo no passo 5.

Mais dois códigos nomeiam um serviço de que o trilho depende. Eles não se referem à sua configuração. Repita-os:

| Resposta | O serviço que não respondeu |
| - | - |
| `504 PIX-3007` | o Access Manager, quando o trilho pede o próprio token. Ele não respondeu a tempo |
| `503 PIX-3008` | o Access Manager está indisponível |

A [lista de erros do Pix JD](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/pix-jd-error-list.md) tem todos os códigos, com o `detail` exato de cada um.

## Para onde ir agora

> [card] [Variáveis de ambiente](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-environment-variables.md)
>
> A configuração deste trilho no momento do deploy: conectividade com a JD, os endpoints do ledger e do CRM, a hospedagem de QR e os provedores de notificação.

> [card] [Multiorganização e ledgers](https://docs.lerian.studio/pt/interfaces/pix-jd/multi-organization-and-ledgers.md)
>
> Estenda esta configuração para vários livros, ou vários participantes diretos, no mesmo deploy: o catálogo de organizações, como um toggle de funcionalidade.

> [card] [Participantes indiretos](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/indirect-participants.md)
>
> O que é uma participação hospedada, como um crédito de entrada chega a ela, o ciclo de vida dela e toda recusa que ela pode responder.

> [card] [Pix Direto via JD](https://docs.lerian.studio/pt/interfaces/pix-jd/direct-pix-via-jd.md)
>
> Como as movimentações de Pix liquidadas chegam ao Midaz, e como os dois sistemas se correlacionam.

> [card] [Lista de erros do Pix JD](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/pix-jd-error-list.md)
>
> Todo código `PIX-NNNN`, o status dele e o texto `detail` da resposta.


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