API REST

Selos usados na referência: ação filtro GET POST DELETE · Grátis PRO. Tudo o que não traz o selo PRO funciona no plugin grátis. Abaixo de cada gancho e de cada rota está o arquivo e a linha onde ele aparece no código da versão indicada, para você ler o docblock completo no código.

Autenticação

As rotas pedem um usuário com a capacidade manage_woocommerce, que no WooCommerce vem com os papéis Administrador e Gerente de loja. As exceções públicas são POST /customer-returns (protegida pela chave do pedido), os retornos de autorização (GET /prepaid/callback e, no PRO, GET /bling/oauth/callback), o webhook do Bling e as rotas do agente de impressão, que usam o token do agente. Há três jeitos de chamar:

No wp-admin: cookie e nonce

O cookie de login vale na REST junto com o nonce wp_rest no cabeçalho X-WP-Nonce. Gere o nonce no seu plugin, na tela onde o JavaScript roda:

// No seu plugin, na tela onde o JavaScript vai chamar a REST:
wp_enqueue_script( 'meu-plugin-admin', plugins_url( 'admin.js', __FILE__ ), [ 'wp-api-fetch' ], '1.0.0', true );
wp_localize_script( 'meu-plugin-admin', 'meuPlugin', [
	'restUrl' => rest_url( 'infixs-correios-automatico/v1' ),
	'nonce'   => wp_create_nonce( 'wp_rest' ),
] );

// admin.js
const resposta = await fetch( `${ meuPlugin.restUrl }/orders/1234`, {
	credentials: 'same-origin',
	headers: { 'X-WP-Nonce': meuPlugin.nonce },
} );
const { order } = await resposta.json();

// Ou, com o wp-api-fetch (o nonce do WordPress já vai junto):
const dados = await wp.apiFetch( { path: '/infixs-correios-automatico/v1/orders/1234' } );

De fora do WordPress: senha de aplicação

Crie uma senha de aplicação (WordPress 5.6+, com HTTPS) em Usuários → Perfil para um usuário dedicado com o papel Gerente de loja, e envie em Authorization: Basic. Guarde a senha no cofre do ERP, fora do código.

curl -u 'integracao-erp:SENHA-DE-APLICACAO' \
  -H 'Content-Type: application/json' \
  -X POST 'https://sua-loja.com.br/wp-json/infixs-correios-automatico/v1/preposts' \
  -d '{"order_id":1234,"shipping_item_id":77,"invoice_number":"1234","invoice_key":"35261112345678000195550010000012341123456781"}'

Dentro do PHP: rest_do_request()

A chamada interna passa pelas mesmas permissões da rota. Em WP-Cron, Action Scheduler, webhook ou WP-CLI, defina antes um usuário com manage_woocommerce (wp_set_current_user()). Para código no mesmo site, as ações e os filtros costumam ser o caminho mais direto; a REST interna é útil quando você quer exatamente o comportamento da rota, como o rastreio que POST /preposts grava.

$request = new WP_REST_Request( 'POST', '/infixs-correios-automatico/v1/preposts' );
$request->set_body_params( [
	'order_id'       => 1234,
	'invoice_number' => '1234',
	'invoice_key'    => '35261112345678000195550010000012341123456781',
] );

$response = rest_do_request( $request ); // Precisa de um usuário atual com manage_woocommerce.

if ( $response->is_error() ) {
	$erro = $response->as_error(); // WP_Error com o code e o status da rota.
} else {
	$prepost = $response->get_data(); // [ 'id' => 87, 'object_code' => 'AB123456789BR', ... ]
}

// Rotas que leem só JSON (marcadas "corpo JSON" nas tabelas):
// $request->set_header( 'Content-Type', 'application/json' );
// $request->set_body( wp_json_encode( [ 'printed' => true ] ) );

Respostas de erro

Os erros seguem o formato do WordPress, { "code", "message", "data": { "status" } }. Trate pelo campo code. Erros vindos dos Correios chegam como http_error, com o status deles em data.status (e o código dos Correios em data.error_code, quando há). Erros do Contrato pré-pago começam com prepaid_ (ex.: prepaid_insufficient_balance 402, com data.balance_cents, data.price_cents e data.topup_url).

{
  "code": "invalid_recipient_neighborhood",
  "message": "O campo Bairro do destinatário é obrigatório quando o CEP termina com 000.",
  "data": { "status": 400, "prepost_error_recorded": true }
}

Pedidos

Pré-postagem

Parâmetros de POST /preposts

Aceita JSON, formulário ou query string.

• Com invoice_key e invoice_number (sem withDce), a pré-postagem vai com a NF-e e sem DC-e.
• Com withDce, a escolha vale como veio.
• Sem nenhum documento, o plugin procura a NF-e do pedido (filtro infixs_correios_automatico_order_invoice e metas): NF-e se houver, senão DC-e.
• A nota informada fica gravada nos metas do pedido, e o código do objeto entra como código de rastreio.
• Ordem das conferências: order_id, documento fiscal, contrato, pedido (método, endereço), remetente e, por fim, os Correios. Todo erro de pré-postagem também fica registrado no pedido (prepost_errors) e na central de notificações.

Logística reversa

Etiquetas e impressão

Rastreio

Para todos os códigos de um pedido, use GET /orders/{id} (tracking_codes[]) ou a REST do WooCommerce (tracking_codes).

Outros recursos

Notificações, Contrato pré-pago, frete e configurações. As rotas de credenciais do contrato e de aceite dos termos são exclusivas do painel e ficam fora desta referência.

No Contrato pré-pago não há logística reversa, Packet internacional nem suspensão de entrega: essas rotas respondem 422 (prepaid_reverse_not_supported, prepaid_packet_not_supported, prepaid_not_supported).

Packet internacional

Unitização e fatura CN-38 do Packet internacional (Contrato Próprio). Apesar do nome, invoice-units não tem relação com NF-e.

Rotas do PRO

PRO As rotas do PRO entram no namespace do grátis, infixs-correios-automatico/v1, pelo gancho infixs_correios_automatico_register_routes. Para integrações, as mais úteis são as do pedido no Correios LOG+; as demais atendem o painel, a integração nativa com o Bling e o agente de impressão da Infixs. As rotas do Bling, do Correios LOG+ e das embalagens existem quando o recurso é suportado pela combinação de versões. O namespace próprio do PRO, infixs-correios-automatico-pro/v1, guarda só a consulta interna da licença e fica fora desta referência.

Erros do Correios LOG+: logplus_order_not_found 404, logplus_not_created 409 (XML antes de o pedido existir no armazém), logplus_license_inactive 403, logplus_not_configured 409, logplus_invalid_xml 422 (vazio, maior que 1 MB, ilegível ou sem xPed, com reason = xped), logplus_order_closed 409, logplus_busy 409, logplus_invalid_order 422 (no envio, quando o pedido não pode ir ao armazém como está; o motivo vem na mensagem), logplus_invalid_period 400 e logplus_period_too_long 422 (em GET /logplus/orders: datas AAAA-MM-DD, a final igual ou depois da inicial, período de até 10 dias) e logplus_http_error 502 (com correios_status).

REST do WooCommerce

Exemplos completos

Criar a pré-postagem com a NF-e

POST /wp-json/infixs-correios-automatico/v1/preposts
Content-Type: application/json

{
  "order_id": 1234,
  "shipping_item_id": 77,
  "invoice_number": "1234",
  "invoice_key": "35261112345678000195550010000012341123456781"
}

Resposta (o modelo de pré-postagem, o mesmo das outras rotas desta seção):

{
  "id": 87,
  "order_id": 1234,
  "vendor_id": null,
  "shipping_item_id": 77,
  "expire_at": "2026-12-04 00:00:00",
  "created_at": "2026-11-04 10:15:02",
  "object_code": "AB123456789BR",
  "service": "SEDEX",
  "status": "Pré-postado",
  "status_code": 2,
  "payment_type": "A faturar",
  "dce": false,
  "cancel_reason": null,
  "dce_icms_blocked": false
}

status_code: 1 Preatendido, 2 Pré-postado, 3 Postado, 4 Expirado, 5 Cancelado, 6 Estornado, 7 Pendente. dce_icms_blocked indica que a DC-e foi recusada porque a loja é contribuinte de ICMS (rejeição 812), sinal de que o envio precisa da NF-e. Para forçar a DC-e mesmo com NF-e no pedido: { "order_id": 1234, "withDce": true }.

Consultar o pedido, a nota e as pré-postagens

GET /wp-json/infixs-correios-automatico/v1/orders/1234

{
  "status": "success",
  "order": {
    "id": 1234,
    "status": "processing",
    "status_label": "Processando",
    "total_amount": 17580,
    "customer": {
      "id": 12,
      "name": "Cliente Exemplo",
      "email": "[email protected]",
      "phone_number": "11900000000",
      "document": "000.000.000-00",
      "address": { "postal_code": "01001-000", "street": "Rua Exemplo", "number": "100", "complement": "", "neighborhood": "Centro", "city": "São Paulo", "state": "SP", "country": "BR" }
    },
    "shipping_items": [
      { "item_id": 77, "instance_id": 5, "method_title": "SEDEX", "cost": 1590, "volume_index": 0, "volume_total": 0, "vendor_id": null, "is_correios": true, "carrier": "correios", "shipping_product_code": "03220" }
    ],
    "invoice": { "invoice_number": "1234", "invoice_key": "35261112345678000195550010000012341123456781", "model": "55", "source": "meu-plugin-nfe", "source_label": "Meu Plugin de NF-e" },
    "waiting_invoice": false,
    "invoice_status": { "state": "authorized", "tone": "success", "label": "NF-e nº 1234", "detail": "", "source": "meu-plugin-nfe", "source_label": "Meu Plugin de NF-e", "danfe": "ready", "actions": [] },
    "meta_data": [
      { "key": "_infixs_correios_automatico_invoice_number", "value": "1234" },
      { "key": "_infixs_correios_automatico_invoice_key", "value": "35261112345678000195550010000012341123456781" }
    ],
    "preposts": [
      { "id": 87, "order_id": 1234, "vendor_id": null, "shipping_item_id": 77, "object_code": "AB123456789BR", "service": "SEDEX", "status": "Pré-postado", "status_code": 2, "payment_type": "A faturar", "dce": false, "cancel_reason": null, "dce_icms_blocked": false, "expire_at": "2026-12-04 00:00:00", "created_at": "2026-11-04 10:15:02" }
    ],
    "prepost_errors": [],
    "tracking_codes": [
      { "id": 301, "code": "AB123456789BR", "vendor_id": null, "shipping_item_id": 77, "carrier": "correios" }
    ]
  }
}

Pedidos aguardando a NF-e

PRO Recortado; cada item de orders tem o formato completo de GET /orders/{id}.

GET /wp-json/infixs-correios-automatico/v1/orders?pending=invoice&status=&per_page=50

{
  "status": "success",
  "page": 1,
  "per_page": 50,
  "total_results": 2,
  "total": 2,
  "total_pages": 1,
  "orders": [ { "id": 1240, "waiting_invoice": true, "invoice_status": { "state": "pending", "label": "Pré-postagem automática aguardando a NF-e" } } ]
}

Reler a pré-postagem nos Correios

POST /wp-json/infixs-correios-automatico/v1/preposts/87/sync

{ "id": 87, "object_code": "AB123456789BR", "status": "Postado", "status_code": 3, "dce": false, "cancel_reason": null, "dce_icms_blocked": false }

Cancelar a pré-postagem

PRO Com o PRO ativo:

POST /wp-json/infixs-correios-automatico/v1/preposts/87/cancel

{ "success": true }

Só com o grátis, a rota responde 400:

{
  "code": "cancel_prepost_pro_feature",
  "message": "...",
  "data": { "status": 400, "buy_pro_url": "https://..." }
}

Dados da etiqueta com a DANFE

Recortado; cada etiqueta traz também os demais dados do destinatário, os totais e o contrato.

GET /wp-json/infixs-correios-automatico/v1/labels?order_id[]=1234

{
  "status": "success",
  "labels": [
    {
      "order_id": 1234,
      "shipping_item_id": 77,
      "name": "Cliente Exemplo",
      "document": "000.000.000-00",
      "address_postalcode": "01001-000",
      "address_city": "São Paulo",
      "address_state": "SP",
      "carrier": "correios",
      "shipping_product_code": "03220",
      "tracking_code": "AB123456789BR",
      "total_amount": 17580,
      "volume_index": 1,
      "volume_total": 1,
      "items": [ { "name": "Camiseta", "sku": "CAM-01", "quantity": 1, "ncm": "61091000", "amount": 15990 } ],
      "preposts": [ { "id": 87, "object_code": "AB123456789BR", "invoice_number": "1234", "invoice_key": "35261112345678000195550010000012341123456781", "dce": false, "contract_source": "own" } ],
      "invoice": { "invoice_number": "1234", "invoice_key": "35261112345678000195550010000012341123456781", "model": "55", "source": "meu-plugin-nfe", "source_label": "Meu Plugin de NF-e" },
      "danfe_status": "ready",
      "danfe": { "schema": 1, "source": "meu-plugin-nfe", "environment": "production", "key": "35261112345678000195550010000012341123456781", "number": "1234", "series": "1", "operation": "out", "total": 15990 },
      "sender": null
    }
  ]
}

Documento da devolução e reversa

GET /wp-json/infixs-correios-automatico/v1/preposts/reverse/document?order_id=1234&shipping_item_id=77

{ "source": "outbound_invoice", "emite_dce": false, "invoice_number": "1234", "invoice_key": "35261112345678000195550010000012341123456781" }

POST /wp-json/infixs-correios-automatico/v1/preposts/reverse
Content-Type: application/json

{ "order_id": 1234, "shipping_item_id": 77 }

NF-e pela REST do WooCommerce

PRO Com as chaves da REST do WooCommerce ou uma senha de aplicação de um usuário que edita pedidos:

PUT /wp-json/wc/v3/orders/1234
Content-Type: application/json

{
  "meta_data": [
    { "key": "_infixs_correios_automatico_invoice_number", "value": "1234" },
    { "key": "_infixs_correios_automatico_invoice_key", "value": "35261112345678000195550010000012341123456781" }
  ]
}

XML da NF-e para o Correios LOG+

PRO Requisição e resposta (recortada):

POST /wp-json/infixs-correios-automatico/v1/logplus/order/1234/xml
Content-Type: application/json

{ "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc ...>...<compra><xPed>987654</xPed></compra>...</nfeProc>" }

{
  "order_id": 1234,
  "enabled": true,
  "logplus_order": true,
  "id": "987654",
  "number": "1234",
  "service": "39888",
  "service_label": "SEDEX LOG+",
  "status": "created",
  "xml_status": "sent",
  "xml_attempts": 1,
  "has_xml": true,
  "xml_error": null,
  "xml_retrying": false,
  "error": null
}