PHPackages                             notagil/integration-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. [API Development](/categories/api)
4. /
5. notagil/integration-sdk

ActiveLibrary[API Development](/categories/api)

notagil/integration-sdk
=======================

PHP SDK for the NotaAgil public integration API.

v0.2.0(2w ago)1122↓26.2%11MITTypeScriptPHP ^8.2CI failing

Since May 18Pushed 2w agoCompare

[ Source](https://github.com/sabbajohn/notagil-integration-sdk)[ Packagist](https://packagist.org/packages/notagil/integration-sdk)[ Docs](https://github.com/sabbajohn/notagil-integration-sdk)[ RSS](/packages/notagil-integration-sdk/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (10)Dependencies (2)Versions (11)Used By (1)

NotaAgil Integration SDK
========================

[](#notaagil-integration-sdk)

SDKs oficiais para a API publica de integracao da NotaAgil.

Este repositorio publica dois pacotes a partir do mesmo codigo fonte:

- PHP/Composer: `notagil/integration-sdk`
- TypeScript/npm: `@notagil/integration-sdk`

O contrato OpenAPI versionado fica em `openapi/integration-v1.yaml`.

A estrutura recomendada para preview e emissao fiscal por `operation_code`, alem do payload canonico PT-BR para NFSe Nacional na superficie direta, esta documentada em [docs/payload-emissao.md](docs/payload-emissao.md).

Release Atual
-------------

[](#release-atual)

`v0.2.0` consolida o contrato canonico NFSe multi-provider na superficie publica, com `provider-info` em campos PT-BR canonicos e helpers de validacao local para o payload direto Nacional.

Ele cobre autenticacao por bearer token, empresas, configuracao fiscal, certificados, catalogos fiscais, perfis fiscais de emissor, perfis de operacao, atribuicoes de perfil, referencias de aliquota, regras fiscais, readiness/onboarding XML, preview/emissao por `operation_code` com contrato `snapshot`, documentacao da estrutura de emissao, consulta/cancelamento/correcao de documentos, downloads XML/PDF/snapshot, envio direto escopado por empresa, XML direto, entrada NF-e, estoque, agendamentos, produtos, tomadores, webhooks, metricas e billing.

Breaking beta: os aliases sem `companyId` e a emissao por `payload` legado foram removidos. Use sempre rotas/metodos company-scoped com envelope `snapshot`.

Instalacao PHP
--------------

[](#instalacao-php)

```
composer require notagil/integration-sdk:^0.2.0
```

```
use NotaAgil\Integration\NotaAgilClient;

$client = new NotaAgilClient(
    baseUrl: 'https://api.notagil.com.br/api/v1/integrations',
    token: getenv('NOTAGIL_TOKEN'),
);

$companies = $client->companies(['cnpj' => '12345678000199']);
```

O pacote Composer usa o `composer.json` da raiz e carrega as classes de `php/src`.

Instalacao TypeScript
---------------------

[](#instalacao-typescript)

```
npm install @notagil/integration-sdk@^0.2.0
```

```
import { NotagilIntegrationClient } from '@notagil/integration-sdk';

const client = new NotagilIntegrationClient({
  baseUrl: 'https://api.notagil.com.br/api/v1/integrations',
  token: process.env.NOTAGIL_TOKEN!,
});

const companies = await client.listCompanies({ cnpj: '12345678000199' });
const documents = await client.listCompanyDocuments(companies[0].id, { per_page: 20 });
const authorized = await client.waitDocument('pdv-sale-0001', { companyId: companies[0].id });

if (authorized.fiscal_status === 'authorized') {
  const xml = await client.downloadDocumentXml('pdv-sale-0001', companies[0].id);
  const pdf = await client.downloadDocumentPdf('pdv-sale-0001', companies[0].id);

  console.log(authorized.access_key, authorized.protocol, authorized.authorized_at);
  console.log(xml.content); // XML autorizado completo em texto puro.
  console.log(pdf.base64); // PDF/DANFE em base64 sem data URI.
}
```

O pacote npm e publicado a partir do diretorio `typescript/`.

Desenvolvimento
---------------

[](#desenvolvimento)

Atualize `openapi/integration-v1.yaml` a partir do `fiscal-platform-api` antes de gerar novos tipos.

```
cd typescript
npm ci
npm run generate:types
npm run build
npm test
npm run pack:dry-run
```

```
composer install
composer validate --strict
composer test
```

O comando `composer test` (ou `composer test:sdk`) e o switch de validacao completa:

- `SDK_TEST_SWITCH=on` (padrao): roda testes PHP + TypeScript.
- `SDK_TEST_SWITCH=off`: pula a validacao e encerra com sucesso.
- `SDK_E2E_SWITCH=on`: inclui teste ponta a ponta em homologacao (chamadas reais).
- `SDK_E2E_SWITCH=off` (padrao): nao executa E2E.

Exemplo:

```
SDK_TEST_SWITCH=off composer test:sdk
```

E2E em homologacao:

```
SDK_E2E_SWITCH=on NOTAGIL_TOKEN=seu_token composer test
```

Detalhes completos de payload, variaveis e fluxo em [docs/e2e-homologacao.md](docs/e2e-homologacao.md).

Se quiser rodar apenas o teste PHP a partir da raiz:

```
composer test:php
```

Se quiser rodar apenas E2E:

```
composer test:e2e
```

Tambem e possivel trabalhar somente no pacote PHP isolado:

```
cd php
composer install
composer test
```

Publicacao
----------

[](#publicacao)

1. Atualize o changelog.
2. Atualize a versao em `typescript/package.json`.
3. Rode as validacoes locais.
4. Crie a tag semver, por exemplo:

```
git tag v0.2.0
git push origin v0.2.0
```

O workflow `.github/workflows/release-packages.yml` publica o pacote TypeScript no npm usando `NPM_TOKEN`.

Para PHP, cadastre este repositorio no Packagist como `notagil/integration-sdk`. O Packagist deve ler o `composer.json` da raiz; configure o webhook do GitHub ou os secrets `PACKAGIST_USERNAME` e `PACKAGIST_TOKEN` para atualizar o pacote automaticamente.

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance97

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity42

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

Every ~1 days

Total

10

Last Release

14d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/299b8502a3c252fd7733814f2219701cb8b38d15519fabb338ee47e6564c48a0?d=identicon)[sabbajohn](/maintainers/sabbajohn)

---

Top Contributors

[![sabbajohn](https://avatars.githubusercontent.com/u/45358247?v=4)](https://github.com/sabbajohn "sabbajohn (23 commits)")

---

Tags

sdknfenfsenfcefiscalnotagil

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/notagil-integration-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/notagil-integration-sdk/health.svg)](https://phpackages.com/packages/notagil-integration-sdk)
```

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.3k532.1M2.5k](/packages/aws-aws-sdk-php)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3751.2M45](/packages/tencentcloud-tencentcloud-sdk-php)[clicksend/clicksend-php

351.6M11](/packages/clicksend-clicksend-php)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

232.5k](/packages/eslazarev-wildberries-sdk)[yoti/yoti-php-sdk

Yoti SDK for quickly integrating your PHP backend with Yoti

27565.3k1](/packages/yoti-yoti-php-sdk)[files.com/files-php-sdk

Files.com PHP SDK

2478.1k](/packages/filescom-files-php-sdk)

PHPackages © 2026

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