backend-php

Backend PHP – Orderbook & Pagamentos

Este documento reúne as instruções de execução e, principalmente, o contrato HTTP dos endpoints relacionados ao fluxo de orderbook/pagamentos. Use-o como referência ao implementar as chamadas no frontend.

Como rodar localmente

1. ./bin/setup – recria o banco usando as credenciais do .env e aplica todas as migrations.
2. composer install – instala dependências PHP.
3. X_LISTEN=127.0.0.1:8000 php public/index.php – sobe a API localmente.

A aplicação também traz um build Deb (ver trecho fpm no final deste arquivo) caso seja necessário gerar um pacote.

Convenções gerais

• Base URL: http://localhost:8000 (ajuste conforme ambiente).
• Autenticação: todos os endpoints abaixo exigem JWT (Authorization: Bearer <token>), exceto quando indicado.

• Formato de resposta: todos usam ResponseLib e retornam o seguinte envelope:

  {
  "status": "ok" | "failed",
  "msg": "[100] Request ok." | "<detalhe de erro>",
  "code": "S_*" | "E_*",
  "data": { ... } | []
  }
  

Fluxo resumido

1. /token/orderbook – atualiza um token e cria uma ordem aberta.
2. /orderbook/filter – frontend lista ordens por estado/commodity.
3. /orderbook/payment – inicia o pagamento (gera PIX e IDs externos).
4. /orderbook/transfer – após o pagamento concluir (Woovi → webhook atualiza status), transfere o token para a carteira da empresa.
5. /b3/payment/confirm – confirma status do pagamento associado à CPR e dispara registro na B3/criação de token.

As seções a seguir detalham os contratos JSON de cada etapa.

---

1. POST /token/orderbook

Cria uma ordem no orderbook para um token existente (atualiza o valor do token e registra a ordem como STATUS_OPEN).

Campo	Tipo / Regra
cpr_id	inteiro positivo
value	numérico (será arredondado para inteiro)
state	string não vazia (UF, ex.: "SP")
commodity_type	string não vazia (ex.: "SOJA")
token_external_id	string não vazia – precisa bater com o token

Exemplo de request

{
  "cpr_id": 42,
  "value": 150000.75,
  "state": "sp",
  "commodity_type": "SOJA",
  "token_external_id": "TOKEN_ABC123"
}

Sucesso (200 – S_ORDERBOOK_CREATED)

{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_ORDERBOOK_CREATED",
  "data": {
    "message": "Token atualizado e ordem registrada com sucesso",
    "token_id": 99,
    "orderbook_id": 321
  }
}

Principais erros

• 400 – E_VALIDATE: falha de validação (cpr_id, campos vazios etc.).
• 404 – E_TOKEN_NOT_FOUND: nenhum token encontrado para a CPR informada.
• 409 – E_TOKEN_MISMATCH: o token_external_id informado não corresponde ao da CPR.
• 500 – E_ORDERBOOK: falha ao atualizar token/criar ordem.

---

2. POST /orderbook/filter

Lista ordens abertas por estado e tipo de commodity.

Campo	Tipo / Regra
state	string não vazia
commodity_type	string não vazia

Request

{
  "state": "SP",
  "commodity_type": "SOJA"
}

Sucesso (200)

• S_ORDERBOOK_FILTER: quando há ordens.

• S_ORDERBOOK_EMPTY: lista vazia.

  {
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_ORDERBOOK_FILTER",
  "data": {
  "state": "SP",
  "commodity_type": "SOJA",
  "orders": [
    {
      "orderbook_id": 321,
      "orderbook_amount": "1000",
      "token_external_id": "TOKEN_ABC123",
      "status_id": 0,
      "token_commodities_value": 150000,
      "token_commodities_amount": 1000,
      "chain_id": 1,
      "wallet_id": 10
    }
  ]
  }
  }
  

Erros comuns

• 400 – E_VALIDATE: campos ausentes/invalidos.
• 500 – E_DATABASE: erro ao consultar o orderbook.

---

3. POST /orderbook/payment

Inicia o processo de pagamento para uma ordem aberta. Retorna o código PIX/ID externo para o frontend exibir ao usuário.

Campo	Tipo / Regra
orderbook_id	inteiro positivo

Request

{
  "orderbook_id": 321
}

Sucesso (200 – S_ORDERBOOK_PAYMENT)

{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_ORDERBOOK_PAYMENT",
  "data": {
    "orderbook_id": 321,
    "payment_id": 555,
    "payment_code": "000201...",
    "payment_external_id": "PAY_a1b2c3d4",
    "token_external_id": "TOKEN_ABC123"
  }
}

Erros possíveis

• 400 – E_VALIDATE: orderbook_id inválido.
• 404 – E_NOT_FOUND: orderbook inexistente.
• 409 – E_ORDERBOOK_STATUS: ordem não está STATUS_OPEN.
• 422 – E_TOKEN_VALUE: valor calculado do token ≤ 0.
• 500 – E_DATABASE ou E_PAYMENT: problemas ao ler base ou iniciar o pagamento.

---

4. POST /orderbook/transfer

Verifica se o pagamento (Woovi) foi concluído e transfere o token para a carteira da empresa autenticada. Deve ser chamado após o webhook da Woovi marcar o pagamento como concluído.

Campo	Tipo / Regra
external_id	string não vazia (ID Woovi)
token_external_id	string não vazia

Request

{
  "external_id": "PAY_a1b2c3d4",
  "token_external_id": "TOKEN_ABC123"
}

Sucesso

• 200 – S_TOKEN_TRANSFERRED: transferência executada e orderbook marcado como concluído.

• 200 – S_TOKEN_ALREADY_TRANSFERRED: ordem já estava concluída anteriormente.

  {
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_TOKEN_TRANSFERRED",
  "data": {
  "orderbook_id": 321,
  "token_external_id": "TOKEN_ABC123",
  "destination_address": "0x8AC9...",
  "transfer_output": "Transfer success",
  "transfer_error": ""
  }
  }
  

Erros principais

• 400 – E_VALIDATE: body inválido.
• 401 – E_VALIDATE: empresa não encontrada no contexto JWT.
• 403 – E_FORBIDDEN: orderbook pertence a outra empresa.
• 404 – E_NOT_FOUND: pagamento ou orderbook inexistente / E_WALLET_NOT_FOUND para carteira.
• 409 – E_PAYMENT_PENDING: pagamento ainda não tem status_id = 1.
• 500 – E_DATABASE ou E_TRANSFER: falhas ao consultar dados ou executar o comando de transferência.

---

5. POST /b3/payment/confirm

Confirma o status do pagamento ligado a uma CPR (usa payment_id) e, se concluído, envia a CPR para a B3 e cria o token correspondente. Necessita header Authorization (JWT) e pode receber o token B3 via body ou headers customizados (X-B3-Authorization).

Campo	Tipo / Regra
payment_id	inteiro positivo
b3_access_token	opcional (string). Pode vir também via header

Request

{
  "payment_id": 555,
  "b3_access_token": "Bearer ..."
}

Sucesso (200 – S_CPR_SENT)

{
  "status": "ok",
  "msg": "[100] Request ok.",
  "code": "S_CPR_SENT",
  "data": {
    "message": "CPR enviada e token criado com sucesso",
    "payment_id": 555,
    "b3_response": {"status": "OK"},
    "token_id": 99,
    "token_external_id": "TOKEN_ABC123",
    "tx_hash": "0x..."
  }
}

Erros principais

• 400 – E_VALIDATE: payment_id ausente/≤0.
• 404 – E_NOT_FOUND: pagamento inexistente / E_CPR_NOT_FOUND (sem CPR ligada).
• 409 – E_PAYMENT_PENDING: pagamento ainda pendente (status_id = 0).
• 409 – E_PAYMENT_STATUS: status diferente de concluído.
• 502 – E_EXTERNAL: falha ao comunicar com a B3.
• 500 – E_TOKEN_CREATE / E_CPR_UPDATE: problemas internos ao gerar token ou ligar CPR → token.

---

Observações adicionais

• O webhook da Woovi (POST /woovi/webhook) marca o pagamento como concluído (status_id = 1). Esse passo é obrigatório para que /orderbook/transfer aceite a transferência.
• Todos os valores monetários são tratados em inteiros (centavos) após arredondamento.
• Utilize os code (S_*/E_*) para tratar estados no frontend sem depender apenas de mensagens.

Geração de pacote Deb (opcional)

``` fpm -s dir -t deb \ -n php-api -v 1.0.0 \ -C build/php-api \ --prefix / \ --description "API PHP php-api (SmartPay)" \ --license "Proprietary" \ --vendor "SmartPay" \ --maintainer "lucas.joaquim@smartpay.com.vc" \ --architecture all \ --deb-no-default-config-files \ --config-files /etc/php-api \ --depends "php8.2-cli | php-cli (>= 8.2)" \ opt/php-api etc/php-api var/log/php-api Created package {:path=>"php-api_1.0.0_all.deb"}