PHPackages                             betocampoy/champs-jadlog-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. betocampoy/champs-jadlog-sdk

ActiveLibrary[HTTP & Networking](/categories/http)

betocampoy/champs-jadlog-sdk
============================

SDK PHP da Champs para integração com a Jadlog (frete, pedidos, tracking, DACTE, PUDOs, QRCode e DCE)

v1.0.0(1mo ago)04MITPHPPHP >=8.2

Since Apr 23Pushed 1mo agoCompare

[ Source](https://github.com/betocampoy/champs-jadlog-sdk)[ Packagist](https://packagist.org/packages/betocampoy/champs-jadlog-sdk)[ RSS](/packages/betocampoy-champs-jadlog-sdk/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (3)Versions (2)Used By (0)

betocampoy/champs-jadlog-sdk
============================

[](#betocampoychamps-jadlog-sdk)

SDK PHP da **Champs** para integração com a **Jadlog**.

Esta versão já inclui:

- suporte a **DC-e** no bloco `dfe` com `tpDocumento = 5`
- DTOs para payloads mais previsíveis
- config de endpoints por **ambiente**
- **fallback em cascata** entre múltiplas URLs por serviço
- histórico da última transação para debug e persistência em banco
- callback opcional por tentativa para log na aplicação

Endpoints cobertos
------------------

[](#endpoints-cobertos)

- inclusão de pedido
- cancelamento de pedido
- tracking completo
- tracking simples
- simulador de frete
- consulta XML do DACTE
- PUDOs por CEP
- PUDOs sem CEP
- QRCode pickup/dropoff
- inclusão de tratativa

Requisitos
----------

[](#requisitos)

- PHP 8.2+
- Composer
- `symfony/http-client` para o adapter HTTP padrão

Instalação
----------

[](#instalação)

```
composer require betocampoy/champs-jadlog-sdk
```

Namespace principal
-------------------

[](#namespace-principal)

```
use BetoCampoy\Champs\JadlogSdk\JadlogClient;
```

Criação do client
-----------------

[](#criação-do-client)

### Simples

[](#simples)

```
use BetoCampoy\Champs\JadlogSdk\JadlogClient;

$client = JadlogClient::create('SEU_TOKEN');
```

### Escolhendo ambiente

[](#escolhendo-ambiente)

```
$client = JadlogClient::create(
    token: 'SEU_TOKEN',
    environment: 'production',
);
```

### Com arquivo de endpoints próprio

[](#com-arquivo-de-endpoints-próprio)

```
use BetoCampoy\Champs\JadlogSdk\Http\SymfonyHttpClientAdapter;

$client = JadlogClient::create(
    token: 'SEU_TOKEN',
    endpointsFile: __DIR__ . '/config/jadlog_endpoints.php',
    http: new SymfonyHttpClientAdapter(),
    environment: 'homologation',
);
```

### Com callback para logar tentativas

[](#com-callback-para-logar-tentativas)

```
use BetoCampoy\Champs\JadlogSdk\Http\RequestAttemptResult;

$client = JadlogClient::create(
    token: 'SEU_TOKEN',
    attemptListener: function (RequestAttemptResult $attempt): void {
        // salvar em banco, monolog, etc.
        // $attempt->toArray()
    },
);
```

DTOs disponíveis
----------------

[](#dtos-disponíveis)

- `OrderRequest`
- `QuoteRequest`
- `QuoteItem`
- `Party`
- `DfeDocument`
- `Volume`
- `TrackingQuery`

Builders disponíveis
--------------------

[](#builders-disponíveis)

- `OrderBuilder`
- `QuoteBuilder`
- `TrackingQueryBuilder`

Enum de documento fiscal
------------------------

[](#enum-de-documento-fiscal)

```
use BetoCampoy\Champs\JadlogSdk\Enum\DocumentType;

DocumentType::DECLARACAO; // 0
DocumentType::NF;         // 1
DocumentType::NFE;        // 2
DocumentType::CTE;        // 4
DocumentType::DCE;        // 5
```

Como a configuração de endpoints funciona
-----------------------------------------

[](#como-a-configuração-de-endpoints-funciona)

O arquivo `config/endpoints.php` agora usa:

- ambiente atual em `environment`
- mapa por ambiente em `environments`
- lista ordenada de `uris` por serviço

Exemplo resumido:

```
return [
    'environment' => 'production',
    'environments' => [
        'production' => [
            'frete_valor' => [
                'method' => 'POST',
                'uris' => [
                    'https://www.jadlog.com.br/embarcador/api/frete/valor',
                    'https://www.jadlog.com/embarcador/api/frete/valor',
                ],
            ],
        ],
    ],
];
```

Regra de fallback
-----------------

[](#regra-de-fallback)

Quando houver mais de uma URL para o mesmo serviço, o SDK tenta a próxima URL em caso de:

- exceção de transporte
- timeout
- erro de conexão
- HTTP `500`, `502`, `503`, `504`

Ele **não** troca de URL em erros típicos de negócio, como `400`, `401`, `403` ou payload inválido.

Debug e persistência de request/response
----------------------------------------

[](#debug-e-persistência-de-requestresponse)

Após qualquer chamada, você pode recuperar:

```
$client->getLastRequestJson();
$client->getLastResponseRaw();
$client->getLastTransaction();
```

### Exemplo de uso

[](#exemplo-de-uso)

```
$response = $client->quote($payload);

$requestJson = $client->getLastRequestJson();
$responseRaw = $client->getLastResponseRaw();
$transaction = $client->getLastTransaction();

// $transaction?->toArray()
```

`getLastTransaction()` devolve um objeto com:

- serviço chamado
- URL final usada com sucesso
- lista de tentativas
- request body
- response body
- status HTTP final

---

Exemplos de uso
===============

[](#exemplos-de-uso)

1) Simulador de frete com builder
---------------------------------

[](#1-simulador-de-frete-com-builder)

```
use BetoCampoy\Champs\JadlogSdk\Builders\QuoteBuilder;
use BetoCampoy\Champs\JadlogSdk\JadlogClient;

$client = JadlogClient::create('SEU_TOKEN');

$payload = QuoteBuilder::make()
    ->cepOrigem('14801000')
    ->cepDestino('04094002')
    ->modalidade(3)
    ->cnpj('00000000000000')
    ->conta('000000')
    ->peso(750)
    ->valorDeclarado(120.00)
    ->build();

$result = $client->quote($payload, pesoEmGramas: true);
```

2) Simulador de frete com DTO
-----------------------------

[](#2-simulador-de-frete-com-dto)

```
use BetoCampoy\Champs\JadlogSdk\Dto\QuoteItem;
use BetoCampoy\Champs\JadlogSdk\Dto\QuoteRequest;

$request = new QuoteRequest([
    new QuoteItem(
        cepori: '14801000',
        cepdes: '04094002',
        peso: 0.75,
        cnpj: '00000000000000',
        modalidade: 3,
        vldeclarado: 120.00,
        conta: '000000',
    ),
]);

$result = $client->quote($request);
```

3) Inclusão de pedido com DTO e DC-e
------------------------------------

[](#3-inclusão-de-pedido-com-dto-e-dc-e)

```
use BetoCampoy\Champs\JadlogSdk\Dto\DfeDocument;
use BetoCampoy\Champs\JadlogSdk\Dto\OrderRequest;
use BetoCampoy\Champs\JadlogSdk\Dto\Party;
use BetoCampoy\Champs\JadlogSdk\Dto\Volume;
use BetoCampoy\Champs\JadlogSdk\Enum\DocumentType;

$order = new OrderRequest(
    codCliente: '000001',
    conteudo: 'DECLARACAO DE CONTEUDO',
    pedido: ['PED-123'],
    totPeso: 1.2,
    totValor: 199.90,
    modalidade: 3,
    rem: new Party('Remetente LTDA', '00000000000000', 'Rua A', '100', 'Centro', 'Araraquara', 'SP', '14800000'),
    des: new Party('Destinatário', '11111111111', 'Rua B', '200', 'Centro', 'São Paulo', 'SP', '01000000'),
    dfe: [
        new DfeDocument(
            tpDocumento: DocumentType::DCE,
            danfeCte: '41260111111111111111111111111111111111111111',
            nrDoc: 'DCE123',
            serie: '1',
            valor: 199.90,
        ),
    ],
    volume: [new Volume(1.2, altura: 5, comprimento: 20, largura: 10, identificador: 'VOL-001')],
    tpColeta: 'K',
    tipoFrete: 0,
);

$result = $client->createOrder($order);
```

4) Inclusão de pedido com array puro
------------------------------------

[](#4-inclusão-de-pedido-com-array-puro)

```
$payload = [
    'codCliente' => '000001',
    'conteudo' => 'PRODUTO DIVERSO',
    'pedido' => ['PED-456'],
    'totPeso' => 1.2,
    'totValor' => 199.90,
    'modalidade' => 3,
    'tpColeta' => 'K',
    'tipoFrete' => 0,
    'rem' => [
        'nome' => 'Remetente LTDA',
        'cnpjCpf' => '00000000000000',
        'endereco' => 'Rua A',
        'numero' => '100',
        'bairro' => 'Centro',
        'cidade' => 'Araraquara',
        'uf' => 'SP',
        'cep' => '14800000',
    ],
    'des' => [
        'nome' => 'Destinatário',
        'cnpjCpf' => '11111111111',
        'endereco' => 'Rua B',
        'numero' => '200',
        'bairro' => 'Centro',
        'cidade' => 'São Paulo',
        'uf' => 'SP',
        'cep' => '01000000',
    ],
];

$result = $client->createOrder($payload);
```

5) Cancelamento por shipmentId
------------------------------

[](#5-cancelamento-por-shipmentid)

```
$result = $client->cancelOrderByShipmentId('00000000000000');
```

6) Cancelamento por código
--------------------------

[](#6-cancelamento-por-código)

```
$result = $client->cancelOrderByCodigo('123456789');
```

7) Tracking completo por shipmentId
-----------------------------------

[](#7-tracking-completo-por-shipmentid)

```
$result = $client->track([
    ['shipmentId' => '00000000000000'],
]);
```

8) Tracking simples por código
------------------------------

[](#8-tracking-simples-por-código)

```
$result = $client->track([
    ['codigo' => '000000000'],
], simples: true);
```

9) Tracking com builder
-----------------------

[](#9-tracking-com-builder)

```
use BetoCampoy\Champs\JadlogSdk\Builders\TrackingQueryBuilder;

$query = TrackingQueryBuilder::make()
    ->addShipmentId('00000000000000')
    ->addCodigo('000000001')
    ->build();

$result = $client->track($query);
```

10) Consulta XML do DACTE
-------------------------

[](#10-consulta-xml-do-dacte)

```
$xml = $client->getDacteXml('00000000000000000000000000000000000000000000');
```

11) PUDOs por CEP
-----------------

[](#11-pudos-por-cep)

```
$result = $client->listPudosByCep('02031-100');
```

12) PUDOs filtrando tipos
-------------------------

[](#12-pudos-filtrando-tipos)

```
$result = $client->listPudosByCep('02031-100', 'LOCKER');
$result2 = $client->listPudos('PUBLICO');
```

13) QRCode pickup/dropoff
-------------------------

[](#13-qrcode-pickupdropoff)

```
$base64 = $client->getPickupDropoffQrCode('07334200008233');
```

14) Inclusão de tratativa
-------------------------

[](#14-inclusão-de-tratativa)

```
$result = $client->incluirTratativa([
    'pedido' => '768070338',
    'usuario' => 'romulo',
    'acareacao' => false,
    'observacao' => 'Inclusão via SDK Champs Jadlog',
    'finalizar' => 'N',
]);
```

15) Exemplo de persistência em banco
------------------------------------

[](#15-exemplo-de-persistência-em-banco)

```
$result = $client->createOrder($order);

$requestJson = $client->getLastRequestJson();
$responseRaw = $client->getLastResponseRaw();
$transaction = $client->getLastTransaction();

// persistir no banco
// request_json  => $requestJson
// response_raw  => $responseRaw
// transaction   => json_encode($transaction?->toArray(), JSON_UNESCAPED_UNICODE)
```

Observações sobre DC-e
----------------------

[](#observações-sobre-dc-e)

No manual atualizado da Jadlog, o bloco documental do pedido aceita `tpDocumento = 5` para **DC-e**. A integração usa a DC-e como documento dentro de `dfe`, distinta da etiqueta Jadlog. Isso permite gerar a etiqueta a partir de uma DC-e já autorizada no seu domínio, desde que você monte corretamente os dados documentais e operacionais no payload.

Tratamento de erros
-------------------

[](#tratamento-de-erros)

O SDK lança exceções específicas:

- `ValidationException`
- `TransportException`
- `JadlogException`

Exemplo:

```
use BetoCampoy\Champs\JadlogSdk\Exceptions\TransportException;
use BetoCampoy\Champs\JadlogSdk\Exceptions\ValidationException;

try {
    $result = $client->quote($payload);
} catch (ValidationException $e) {
    // payload inválido
} catch (TransportException $e) {
    // erro de transporte / timeout / todas as URLs falharam
}
```

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance90

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

47d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f716b40e59d9e04a7a6ce607fb14866a53a5160e31456676ec379f25e324e58b?d=identicon)[betocampoy](/maintainers/betocampoy)

---

Top Contributors

[![betocampoy](https://avatars.githubusercontent.com/u/85419774?v=4)](https://github.com/betocampoy "betocampoy (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/betocampoy-champs-jadlog-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/betocampoy-champs-jadlog-sdk/health.svg)](https://phpackages.com/packages/betocampoy-champs-jadlog-sdk)
```

###  Alternatives

[symfony/http-kernel

Provides a structured process for converting a Request into a Response

8.1k853.6M8.2k](/packages/symfony-http-kernel)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.4M195](/packages/sulu-sulu)[web-auth/webauthn-framework

FIDO2/Webauthn library for PHP and Symfony Bundle.

51090.8k2](/packages/web-auth-webauthn-framework)[kimai/kimai

Kimai - Time Tracking

4.7k8.7k1](/packages/kimai-kimai)[bitrix24/b24phpsdk

An official PHP library for the Bitrix24 REST API

10139.4k5](/packages/bitrix24-b24phpsdk)[api-platform/metadata

API Resource-oriented metadata attributes and factories

244.5M180](/packages/api-platform-metadata)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)