REST API v2.5 시스템 운영 중

NFE API 문서

NFE API 문서에 오신 것을 환영합니다. 브라질의 전자 송장(NF-e) 발행, 조회 및 취소를 위한 완전한 API입니다. 자동 세금 계산(ICMS, IPI, PIS/COFINS), XML 생성, SEFAZ 승인 및 관리 시스템과의 통합을 지원합니다.

list_alt

중요한 API 필드

중요 필드 해석

이 섹션에서는 올바른 송장 발행 기능에 필수적인 NFE API의 가장 중요한 필드를 설명합니다.

⚠️ ATTENTION: 이 필드의 올바른 구성은 유효한 송장 발행의 기본입니다. 항상 현행 세금 법률을 참조하십시오.

필드	설명	가능한 값	중요도
`invoice_type`	회사 유형 (법인/개인)	`juridica`, `fisica`	높음 - 세금 체계 정의
`nature_of_operation`	거래 성격 (판매, 반품 등)	Ex: `SALE`, `RETURN`	높음 - CFOP 결정
`transaction_type`	거래 유형 (입력/출력)	`INPUT`, `OUTPUT`	높음 - 세금 흐름 방향
`model`	송장 모델	`nfe`, `nfce`	높음 - 문서 모델
`issuance_type`	발행 유형 (일반, 비상)	`NORMAL`, `CONTINGENCY`	중간 - 발행 모드
`ambiente`	처리 환경	`PRODUCTION`, `HOMOLOGATION`	높음 - 대상 SEFAZ 정의
`cliente`	고객/구매자 유형	`CONSUMER`, `TAXPAYER`	높음 - 세금에 영향
`products.origem`	제품 원산지 (국내/수입)	`0` to `8`	높음 - 과세 결정
`products.indicador_total`	제품이 송장 합계에 포함되는지 여부	`true`, `false`	중간 - 샘플 항목용

💡 TIP: 제품의 경우, origem 필드가 중요합니다: 0-국내산, 1-외국 직수입, 2-국내 시장에서 구매한 외국산 등. 상품 원산지의 전체 표를 참조하십시오.

sync_alt

송장 발행 프로세스 흐름

완전한 NF-e 발행 다이어그램

브라질의 전자 송장 발행의 완전한 흐름, 기업 생성부터 최종 파일 생성까지.

business

1. 기업 등록

브라질의 현지 기업 세무 정보 생성

send

2. 정보 전송

주문 데이터 (사용자, 주소, 제품 세금)

receipt

3. 송장 발행

SEFAZ 승인으로 처리 및 전송

assignment_returned

4. 결과 반환

발행 상태 및 NF-e 데이터

description

5. 파일 생성

송장의 XML 및 PDF

published_with_changes

세무 검증

SEFAZ 검증

check_circle

Success

error

Failure

Initial Setup

Data Processing

Fiscal Issuance

Positive Results

📊 Detailed Flow: The process follows a logical 순서: (1) 기업 구성 → (2) 주문 데이터 수신 → (3) NF-e 처리 및 발행 → (4) 상태 반환 → (5) File generation. The decision point (세무 검증) determines whether the issuance was authorized by SEFAZ.

flash_on

엔드포인트 빠른 참조

모든 NFE API 엔드포인트

사용 가능한 모든 API 엔드포인트의 전체 개요입니다. 이 표를 빠른 참조로 사용하여 문서를 탐색하십시오.

Base URL

https://api.tffiscal.com

경로	HTTP 메서드	기능
business 기업 관리
`/api/company/create`	POST	기업 등록
`/api/company/get_detail`	GET	기업 조회
`/api/company/edit`	POST	기업 수정
`/api/company/get_list`	GET	기업 목록
`/api/company/v2/create`	POST	기업 등록 (간소화)
`/api/company/get_cep_detail`	GET	CEP 조회
`/api/company/get_export_invoice_month_files`	GET	월별 내보내기 파일
category 카테고리/세금 관리
`/api/category/get_list`	GET	세금 카테고리 목록
`/api/category/create`	POST	세금 카테고리 생성
`/api/category/get_detail`	GET	카테고리 상세 조회
`/api/category/edit`	POST	세금 카테고리 수정
`/api/category/delete`	POST	세금 카테고리 삭제
receipt 송장 관리
`/api/invoice/create`	POST	송장 발행
`/api/invoice/get_list`	GET	송장 목록
`/api/invoice/get_detail`	GET	송장 상세 조회
`/api/invoice/refresh`	POST	송장 상태 업데이트
`/api/invoice/cancel`	POST	송장 취소
`/api/invoice/invalid`	POST	송장 번호 무효화
`/api/invoice/return`	POST	송장 반환
`/api/invoice/get_xml`	POST	송장 XML 내보내기
receipt NFC-e (소비자 전자 영수증)
`/api/nfce/company/create`	POST	NFC-e 기업 등록
`/api/nfce/company/update`	POST	NFC-e 기업 수정
`/api/nfce/company/get`	POST	NFC-e 기업 조회
`/api/nfce/create`	POST	NFC-e 발행
`/api/nfce/cancel`	POST	NFC-e 취소
`/api/nfce/get_detail`	POST	NFC-e 조회
`/api/nfce/get_danfe`	POST	NFC-e DANFE 받기
description NFS-e (서비스 전자 청구서)
`/api/nfse/create`	POST	NFS-e 발행
`/api/nfse/cancel`	POST	NFS-e 취소
`/api/nfse/get_danfse`	POST	DANFSE 받기 (PDF)
`/api/nfse/get_xml`	POST	NFS-e XML 다운로드
account_balance 회계사 관리

📋 중요 사항:

모든 엔드포인트는 헤더를 통한 인증이 필요합니다: sign, timestamp, token
기업 등록 및 기업 목록 조회에는 배포자 토큰(b2b_token)을 사용하십시오
Content-Type은 항상 다음이어야 합니다 application/json;charset=utf-8
응답은 JSON 표준을 따르며 필드 success, message and data

200

성공

요청이 성공적으로 처리되었습니다

400

클라이언트 오류

잘못되거나 누락된 데이터

500

서버 오류

내부 서버 오류

account_balance

NFE API

브라질 전자 송장 (NF-e)

브라질의 전자 송장(NF-e) 발행, 조회 및 취소를 위한 완전한 API입니다. 자동 세금 계산(ICMS, IPI, PIS/COFINS), XML 생성, SEFAZ 승인 및 관리 시스템과의 통합을 지원합니다. 현재 브라질 전역에서 제품 송장 발행을 지원합니다.

Base URL (운영 환경)

https://api.tffiscal.com/v1

인증

Headers: sign, timestamp, token

요구사항

유효한 A1 디지털 인증서

sync_alt System Flow

input Input Data

Customer Information
Product Data
Fiscal Information
Transport Data

settings Processing

Data validation
Tax calculation
XML generation
SEFAZ authorization

download Output

Invoice XML
Invoice PDF
DANFE (보조 문서)
Authorization status

주요 엔드포인트

POST /api/company/create

새 발행 회사 등록

디스트리뷰터(b2b) 계정에 연결된 발행 회사를 등록합니다. 회사 데이터가 이미 있는 경우 이 엔드포인트를 사용하세요. 디지털 인증서에서 자동 추출하려면 /api/company/v2/create를 사용하세요.

필수 헤더

헤더	타입	설명
token	string	디스트리뷰터 토큰(b2b — 계정에 `isb2b=true`가 필요)
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
식별
cnpj *	string	발행 회사 CNPJ
name *	string	회사명
ie *	string	주(州) 등록 번호(Inscrição Estadual)
invoice_type *	string	세제(예: `"simples_nacional"`, `"normal"`)
unit *	string	단위 유형
email	string	회사 이메일
주소
cep *	string	우편번호
address *	string	도로명 주소
house_number *	string	주소 번호
town *	string	지구
city *	string	도시
state *	string	UF(주 약어)
디지털 인증서
cert_file *	string	A1 디지털 인증서(.pfx 또는 .p12)의 HTTPS URL
cert_pwd *	string	인증서 비밀번호
번호 및 설정
serie *	int	NF-e 시리즈
number *	int	번호 초기값
is_create_category_template	boolean	기본 세무 카테고리 자동 생성. 기본값: `true`

* 필수 필드.

페이로드 예시

        {
          "cnpj": "12345678000199",
          "name": "Empresa Exemplo LTDA",
          "ie": "123456789",
          "invoice_type": "simples_nacional",
          "unit": "UN",
          "email": "contact@example.com",
          "cep": "01001000",
          "address": "Example Street",
          "house_number": "100",
          "town": "Downtown",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://example.com/cert.pfx",
          "cert_pwd": "senha_do_certificado",
          "serie": 1,
          "number": 1
        }

응답

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/company/v2/create

인증서로 자동 입력하여 회사 등록

/api/company/create의 간소화 버전: API가 디지털 인증서를 검증하고 회사명, IE, 주소 등의 데이터를 내부 조회로 자동 추출합니다. cnpj, cert_file, cert_pwd만 필수입니다.

필수 헤더

헤더	타입	설명
token	string	디스트리뷰터 토큰(b2b — 계정에 `isb2b=true`가 필요)
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
cnpj *	string	발행 회사 CNPJ
cert_file *	string	A1 디지털 인증서(.pfx 또는 .p12)의 HTTPS URL
cert_pwd *	string	인증서 비밀번호
is_create_category_template	boolean	기본 세무 카테고리 자동 생성. 기본값: `true`

* 필수 필드.

페이로드 예시

        {
          "cnpj": "12345678000199",
          "cert_file": "https://example.com/cert.pfx",
          "cert_pwd": "senha_do_certificado"
        }

응답

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/company/edit

회사 데이터 편집

발행 회사 데이터를 업데이트합니다. 변경하려는 필드만 보내세요 — company_id를 제외한 모든 필드는 선택 사항입니다. CNPJ는 변경할 수 없습니다: 보내면 오류를 반환합니다. cep를 업데이트하면 시스템이 자동으로 stateCode와 ibge를 해결합니다. cert_file과 cert_pwd를 함께 보내면 저장 전에 인증서가 검증됩니다.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
company_id *	string	편집할 회사의 ID
name	string	회사명
invoice_type	string	세제
ie	string	주(州) 등록 번호
unit	string	단위 유형
email	string	이메일
cep	string	우편번호(`stateCode`와 `ibge` 자동 업데이트)
address	string	도로명 주소
house_number	string	번호
town	string	지구
city	string	도시
state	string	UF
cert_file	string	새 인증서(.pfx 또는 .p12)의 HTTPS URL. `cert_pwd`와 함께 보내면 저장 전에 검증됩니다
cert_pwd	string	새 인증서 비밀번호
serie	int	새 NF-e 시리즈
number	int	새 초기 번호

* 필수 필드. cnpj를 보내면 오류를 반환합니다.

페이로드 예시

                {
                  "company_id": "comp_789012",
                  "name": "Nova Razão Social LTDA",
                  "email": "new@company.com",
                  "cep": "01310100"
                }

응답

                {
                  "success": true
                }

GET /api/company/get_list

디스트리뷰터 회사 목록

디스트리뷰터(b2b) 계정에 연결된 발행 회사를 페이지네이션으로 나열합니다. 매개변수는 쿼리 문자열로 전달됩니다.

필수 헤더

헤더	타입	설명
token	string	디스트리뷰터 토큰(b2b — 계정에 `isb2b=true`가 필요)
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
page *	int	페이지 번호(≥ 1)
page_size *	int	페이지 크기(1–20)

* 필수 필드.

호출 예시

GET /api/company/get_list?page=1&page_size=10

응답

        {
          "success": true,
          "data": {
            "companys": [
              {
                "company_id": "comp_789012",
                "invoice_type": "simples_nacional",
                "token": "eyJhbGciOiJIUzI1NiIs...",
                "cnpj": "12345678000199",
                "name": "Empresa Exemplo LTDA",
                "ie": "123456789",
                "unit": "UN",
                "email": "contact@example.com",
                "cep": "01001000",
                "address": "Example Street",
                "house_number": "100",
                "town": "Downtown",
                "city": "São Paulo",
                "state": "SP",
                "cert_file": "https://example.com/cert.pfx",
                "cert_pwd": "***",
                "serie": 1,
                "number": 142
              }
            ],
            "page": 1,
            "total": 8,
            "total_pages": 1
          }
        }

GET /api/company/get_detail

인증된 회사 세부 정보

token 헤더로 식별된 회사의 전체 데이터를 등록된 세금 카테고리 목록과 함께 반환합니다. 본문이나 쿼리 문자열을 받지 않습니다.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

호출 예시

GET /api/company/get_detail

응답

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "name": "Empresa Exemplo LTDA",
            "token": "eyJhbGciOiJIUzI1NiIs...",
            "invoice_type": "simples_nacional",
            "cnpj": "12345678000199",
            "ie": "123456789",
            "unit": "UN",
            "email": "contact@example.com",
            "cep": "01001000",
            "address": "Example Street",
            "house_number": "100",
            "town": "Downtown",
            "city": "São Paulo",
            "state": "SP",
            "cert_file": "https://example.com/cert.pfx",
            "cert_pwd": "***",
            "serie": 1,
            "number": 142,
            "categorys": [
              {
                "category_id": "cat_001",
                "descricao": "Venda de mercadoria",
                "disable_difal": false,
                "desconta_icms_pis_cofins": false
              }
            ]
          }
        }

GET /api/company/get_cep_detail

CEP로 주소 조회

브라질 CEP(우편번호)를 해결하여 UF, IBGE 자치단체 코드 및 주소 데이터를 반환합니다. 회사 및 고객 주소 입력에 유용합니다. 디스트리뷰터(b2b) 계정이 필요합니다.

필수 헤더

헤더	타입	설명
token	string	디스트리뷰터 토큰(b2b — 계정에 `isb2b=true`가 필요)
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
cep *	string	브라질 CEP(8자리, 하이픈 유무 관계없음)

* 필수 필드.

호출 예시

GET /api/company/get_cep_detail?cep=01001000

응답

        {
          "success": true,
          "data": {
            "cep": "01001-000",
            "uf": "SP",
            "ibge": 3550308,
            "logradouro": "Praça da Sé",
            "bairro": "Sé",
            "localidade": "São Paulo",
            "ddd": "11"
          }
        }

GET /api/company/get_export_invoice_month_files

생성된 월별 내보내기 파일 목록

현재 연도(시간대 America/Sao_Paulo)에 회사에 대해 이미 생성된 월별 내보내기 파일 목록을 반환합니다. 각 월에는 최대 4개 파일이 있을 수 있습니다: Excel 스프레드시트 1개(Success 상태만) + XML 3개(Success, Canceled, Voided 상태별). 실제로 내보내진 파일만 응답에 표시됩니다 — 새 파일을 생성하려면 /api/invoice/get_xml을 사용하세요.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

호출 예시

GET /api/company/get_export_invoice_month_files

응답

필드	타입	설명
files[]	array	사용 가능한 파일 목록
files[].url	string	OSS의 파일 URL
files[].year	int	기간 연도
files[].month	string	월(1–12)
files[].type	string	파일 형식: `"xlsx"` 또는 `"xml"`
files[].status	string	파일 내 송장의 상태: `"Success"`, `"Canceled"` 또는 `"Voided"`
files[].create	datetime	파일 생성 일시

응답 예시

        {
          "success": true,
          "data": {
            "files": [
              {
                "url": "https://oss.example.com/.../2024_01_success.xlsx",
                "year": 2024,
                "month": "1",
                "type": "xlsx",
                "status": "Success",
                "create": "2024-02-01T03:15:00Z"
              },
              {
                "url": "https://oss.example.com/.../2024_01_success.zip",
                "year": 2024,
                "month": "1",
                "type": "xml",
                "status": "Success",
                "create": "2024-02-01T03:15:30Z"
              }
            ]
          }
        }

GET /api/category/get_list

제품 카테고리 목록

Returns all available categories for fiscal classification.

POST /api/invoice/create

새 송장 발행

NF-e(모델 55)를 발행합니다. 발행 회사는 token 헤더로 식별되며, 본문에 company_id를 보내지 마세요.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	초 단위 Unix 타임스탬프 (5분 유효 시간)

Body — 최상위 필드

필드	타입	설명
식별 및 거래
id	string	멱등성을 위한 클라이언트 측 고유 ID (중복 제거 키 구성)
nature_of_operation *	string	거래 성격 (예: "상품 판매")
transaction_type *	string	유형: `"0"`=입고, `"1"`=출고, `"2"`=수입, `"3"`=수출
model *	string	문서 모델: `"55"`=NF-e
issuance_type *	string	발행 유형 (`"1"`=일반, `"9"`=비상, 등)
ambiente *	string	`"1"`=운영, `"2"`=테스트
finalidade	string	용도: `"1"`=일반, `"2"`=보완, `"3"`=조정, `"4"`=반품
ref_nfe_chave	string	참조된 NF-e의 44자리 액세스 키 (보완/조정/반품용)
is_reopen	boolean	이전에 발행된 NF-e를 재오픈/덮어쓰기
dh_sai_ent	string	출입고 일시 (ISO 8601). 기본값: 현재 타임스탬프
금액 및 할인
total_discount_amount	decimal	송장 총 할인액
troco	decimal	거스름돈 (NFC-e에서 일반적)
seguro	decimal	보험액 (XML의 `vSeg`로 제품에 안분)
outras_despesas	decimal	기타 비용 (XML의 `vOutro`로 제품에 안분)
지표 및 추가 정보
ind_final	string	최종 소비자: `"0"`=B2B, `"1"`=B2C
ind_pres	string	현장 지표: `"1"`=대면, `"2"`=인터넷, `"3"`=전화 서비스 등
informacoes_complementares	string	보충 정보 (`infAdic.infCpl`에 기록됨)
informacoes_fisco	string	세무 당국용 정보 (`infAdic.infAdFisco`에 기록됨)

Body — `cliente` (객체, 필수)

국내 거래(transaction_type 0 또는 1)의 경우: cpf 또는 cnpj, name, endereco, bairro(최소 2자), city, uf, cep가 필수입니다. 수입/수출(transaction_type 2 또는 3)의 경우: name만 필수입니다.

필드	타입	설명
cpf	string	고객 CPF (cnpj 대체)
cnpj	string	고객 CNPJ (cpf 대체)
ie	string	주(州) 등록 번호 (Inscrição Estadual)
name *	string	회사명 / 고객명
endereco	string	주소(도로명)
complemento	string	주소 보충 정보
numero	string	주소 번호
bairro	string	지구 (국내 거래는 최소 2자)
city	string	도시
uf	string	주(UF) — CEP에서 해결된 UF로 덮어씁니다
cep	string	우편번호 (UF 및 도시 검증)
telefone	string	전화번호
email	string	이메일
id_estrangeiro	string	외국인 ID (수입/수출에서 사용)
c_pais	int	BACEN 국가 코드. 기본값: `1058` (브라질)
x_pais	string	국가명. 기본값: `"BRASIL"`

Body — `products[]` (배열, 최소 1개 항목)

각 제품은 과세 정보가 필요합니다: 사전 등록된 세금 카테고리에 대한 category_id 참조, 또는 인라인 구성을 위한 impostos/tax_info 객체 중 하나.

필드	타입	설명
codigo	string	제품 내부 코드
name *	string	제품 설명 (CJK 문자는 제거됨)
ncm *	string	8자리 NCM
cest	string	CEST 코드 (ICMS-ST 적용 시 필수)
gtin	string	GTIN / 바코드
gtin_tributavel	string	과세 단위 GTIN
count *	decimal	수량
unit *	string	상업 단위 (예: "UN", "KG", "MT")
unit_price *	decimal	단가
total_price *	decimal	항목 총액
discount_price	decimal	항목 할인
origem *	int	상품 원산지 (`0`=국내, `1`=해외—직접 수입 등)
indicador_total *	int	NF-e 총액에 포함: `0`=아니요, `1`=예
category_id	string	사전 등록된 세금 카테고리 ID (`impostos`/`tax_info`를 보내지 않으면 필수)
impostos	object	인라인 세금 구성 (`category_id` 대체). 아래 구조 참조
tax_info	object	`impostos` 별칭 (동일 구조)
disable_difal	boolean	이 항목의 DIFAL 계산 비활성화
desconta_icms_pis_cofins	boolean	이 품목에만 PIS/COFINS 과세표준에서 ICMS 공제 (카테고리 설정 재정의)
ii	object	수입세 — CFOP 3.xxx의 경우 필수. 아래 구조 참조
import_declarations	array	수입 신고서(DI) — `transaction_type="2"`의 경우 필수. 아래 구조 참조
nItemPed	int	구매 주문 품목 (I61). 루트의 `id`에서 가져온 `xPed`가 참조하는 주문 내 항목 일련번호. 유효 범위: 1–999999. 기본값: 생략.

Body — `products[].impostos` / `products[].tax_info`

필드	타입	설명
industria	string	기준 산업/세율 (별칭: `aliquota`)
icms
icms.codigo_cfop	string	CFOP
icms.situacao_tributaria	string	ICMS CST/CSOSN
icms.industria	string	ICMS 산업
icms.tipo_pessoa	string	인격 유형 (PF/PJ)
icms.codigo_beneficio_fiscal	string	cBenef (세금 혜택 코드)
ipi
ipi.codigo_enquadramento	string	IPI 법적 분류 코드
ipi.situacao_tributaria	string	IPI CST
ipi.aliquota	string	IPI 세율
ipi.tipo_pessoa	string	인격 유형
pis
pis.situacao_tributaria	string	PIS CST
pis.aliquota	string	PIS 세율
pis.tipo_pessoa	string	인격 유형
cofins
cofins.situacao_tributaria	string	COFINS CST
cofins.aliquota	string	COFINS 세율
cofins.tipo_pessoa	string	인격 유형
is (선택세)
is.cenario	string	IS 시나리오
is.situacao_tributaria	string	IS CST
is.aliquota	string	IS 세율
is.tipo_pessoa	string	인격 유형
ibs_cbs (세제 개혁)
ibs_cbs.situacao_tributaria	string	IBS/CBS CST
ibs_cbs.tipo_pessoa	string	인격 유형
ibs_cbs.classificacao_tributaria	string	IBS/CBS 세금 분류
difal
difal.disable_difal	boolean	항목의 DIFAL 비활성화 (제품 수준 `disable_difal`의 대체)

Body — `products[].ii` (수입세)

필드	타입	설명
vBC	decimal	II 계산 기준
vDespAdu	decimal	통관 비용
vII	decimal	II 금액
vIOF	decimal	IOF 금액

Body — `products[].import_declarations[]`

필드	타입	설명
nDI	string	DI 번호
dDI	string (date)	DI 날짜
xLocDesemb	string	통관 장소
UFDesemb	string	통관 주(州)
dDesemb	string (date)	통관 일자
cExportador	string	수출자 코드
tpViaTransp	int	국제 운송 수단
tpIntermedio	int	중개 유형
vAFRMM	decimal	AFRMM 금액
additions	array	DI 추가 항목 (필드: `nAdicao`, `nSeqAdic`, `cFabricante`, `vDescDI`, `nDraw`)

Body — `shipping_address` / `delivery_address` (객체, 선택)

shipping_address는 픽업 위치(발행자와 다른 경우의 실제 출발지)입니다. delivery_address는 배송 위치(고객과 다른 경우의 실제 도착지)입니다. 지정 시 두 객체 모두 필수: cpf 또는 cnpj, name, endereco, bairro(최소 2자), city, uf, cep. 두 객체는 동일한 구조입니다.

필드	타입	설명
cpf	string	CPF (cnpj 대체)
cnpj	string	CNPJ (cpf 대체)
ie	string	주(州) 등록 번호
name *	string	회사명 / 이름
endereco *	string	주소
complemento	string	보충 정보
number	string	번호 (주의: 필드명은 `number`이며 `numero`가 아닙니다)
bairro *	string	지구
city *	string	도시
uf *	string	주
cep *	string	우편번호
telefone	string	전화번호
email	string	이메일

Body — `transportation` (객체, 선택)

transportation을 생략하면 시스템은 transport_mode="9"(운송료 없음)로 간주합니다.

필드	타입	설명
transport_mode	string	운송료 구분: `"0"`=발행자 부담, `"1"`=수령자 부담, `"2"`=제3자 부담, `"3"`=발송자 자체 운송, `"4"`=수령자 자체 운송, `"9"`=운송료 없음
freight_amount	decimal	총 운송료
carrier_info — 운송업체
carrier_info.cpf	string	운송업체 CPF (cnpj 대체)
carrier_info.cnpj	string	운송업체 CNPJ (cpf 대체)
carrier_info.ie	string	주(州) 등록 번호
carrier_info.name	string	회사명
carrier_info.endereco	string	주소
carrier_info.city	string	도시
carrier_info.uf	string	주
carrier_info.cep	string	우편번호
vehicle_info — 차량
vehicle_info.plate	string	번호판
vehicle_info.uf	string	번호판 주
vehicle_info.rntc	string	RNTC (국가 화물 운송업자 등록)
trailer_info — 트레일러 (vehicle_info와 동일 구조)
trailer_info.plate	string	트레일러 번호판
trailer_info.uf	string	주
trailer_info.rntc	string	RNTC
packages[] — 부피
packages[].qty	int	수량
packages[].gross_weight	decimal	총중량
packages[].net_weight	decimal	순중량
packages[].packaging_type	string	포장 유형
packages[].number	string	번호
packages[].mark	string	마크
packages[].seals	array<string>	봉인
transport_tax_retention_info — 운송료 ICMS 원천징수
transport_tax_retention_info.freight_service_amount	decimal	운송 서비스 금액
transport_tax_retention_info.tax_base	decimal	원천징수 계산 기준
transport_tax_retention_info.tax_rate	decimal	원천징수율
transport_tax_retention_info.cfop	string	CFOP
transport_tax_retention_info.cep	string	우편번호

Body — `pag_info[]` (배열, 선택)

생략 시 시스템은 [{ "payment_method": "01", "payment_indicator": "0" }](현금, 일시불)로 간주합니다.

필드	타입	설명
payment_method *	string	결제 방법: `"01"`=현금, `"02"`=수표, `"03"`=신용카드, `"04"`=직불카드, `"05"`=매장 신용, `"10"`=식료품권, `"11"`=식사권, `"15"`=은행 청구서, `"17"`=PIX, `"90"`=결제 없음, `"99"`=기타
payment_indicator *	string	구분: `"0"`=일시불, `"1"`=할부
payment_value	decimal	지불 금액
card_info — 카드 정보 (payment_method 03/04용)
card_info.integration_type *	string	단말기 연동 유형 (`card_info` 지정 시 필수)
card_info.brand_code *	string	카드 브랜드 (`card_info` 지정 시 필수)
card_info.acquirer_cnpj	string	매입사 CNPJ
card_info.authorization_code	string	승인 코드

* 필수 필드.

간소화된 예시

{
  "nature_of_operation": "Venda de mercadoria",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "2",
  "cliente": {
    "cpf": "12345678909",
    "name": "Cliente Exemplo",
    "endereco": "Rua Exemplo",
    "numero": "100",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01001000",
    "email": "cliente@exemplo.com"
  },
  "products": [
    {
      "codigo": "PROD001",
      "name": "Produto Exemplo",
      "ncm": "85176277",
      "count": 2,
      "unit": "UN",
      "unit_price": 150.00,
      "total_price": 300.00,
      "category_id": "SEU_CATEGORY_ID",
      "origem": 0,
      "indicador_total": 1
    }
  ],
  "pag_info": [
    { "payment_method": "01", "payment_indicator": "0", "payment_value": 300.00 }
  ]
}

완전한 예시 (모든 필드)

{
  "id": "PEDIDO-2026-0001",
  "nature_of_operation": "Venda de mercadoria",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "2",
  "finalidade": "1",
  "ref_nfe_chave": "",
  "is_reopen": false,
  "dh_sai_ent": "",
  "total_discount_amount": 0.00,
  "troco": 0.00,
  "seguro": 0.00,
  "outras_despesas": 0.00,
  "ind_final": "1",
  "ind_pres": "9",
  "informacoes_complementares": "Entrega via transportadora",
  "informacoes_fisco": "ICMS recolhido conforme legislação",
  "cliente": {
    "cpf": "",
    "cnpj": "12345678000199",
    "ie": "123456789",
    "name": "Cliente Exemplo LTDA",
    "endereco": "Av. Paulista",
    "numero": "1000",
    "complemento": "Sala 200",
    "bairro": "Bela Vista",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01310100",
    "telefone": "11999998888",
    "email": "cliente@exemplo.com",
    "id_estrangeiro": "",
    "c_pais": 1058,
    "x_pais": "BRASIL"
  },
  "shipping_address": {
    "cnpj": "98765432000111",
    "name": "Depósito Origem LTDA",
    "ie": "987654321",
    "endereco": "Rua do Depósito",
    "number": "50",
    "complemento": "Galpão 3",
    "bairro": "Industrial",
    "city": "Guarulhos",
    "uf": "SP",
    "cep": "07000000",
    "telefone": "11988887777",
    "email": "deposito@exemplo.com"
  },
  "delivery_address": {
    "cnpj": "12345678000199",
    "name": "Cliente Exemplo LTDA",
    "ie": "123456789",
    "endereco": "Rua de Entrega",
    "number": "25",
    "complemento": "Loja 2",
    "bairro": "Centro",
    "city": "Campinas",
    "uf": "SP",
    "cep": "13010000",
    "telefone": "11977776666",
    "email": "entrega@exemplo.com"
  },
  "products": [
    {
      "codigo": "PROD001",
      "name": "Notebook Dell",
      "ncm": "84713012",
      "cest": "",
      "gtin": "7891234567890",
      "gtin_tributavel": "7891234567890",
      "count": 2,
      "unit": "UN",
      "unit_price": 3500.00,
      "total_price": 7000.00,
      "discount_price": 0.00,
      "origem": 0,
      "indicador_total": 1,
      "category_id": "TF00001",
      "nItemPed": 1
    },
    {
      "codigo": "PROD002",
      "name": "Mouse sem fio",
      "ncm": "84716053",
      "count": 5,
      "unit": "UN",
      "unit_price": 80.00,
      "total_price": 400.00,
      "origem": 0,
      "indicador_total": 1,
      "nItemPed": 2,
      "impostos": {
        "icms": {
          "codigo_cfop": "5102",
          "situacao_tributaria": "00",
          "industria": "",
          "tipo_pessoa": "juridica",
          "codigo_beneficio_fiscal": ""
        },
        "ipi": {
          "codigo_enquadramento": "999",
          "situacao_tributaria": "99",
          "aliquota": "0.00",
          "tipo_pessoa": "juridica"
        },
        "pis": {
          "situacao_tributaria": "01",
          "aliquota": "0.65",
          "tipo_pessoa": "juridica"
        },
        "cofins": {
          "situacao_tributaria": "01",
          "aliquota": "3.00",
          "tipo_pessoa": "juridica"
        },
        "ibs_cbs": {
          "situacao_tributaria": "000",
          "tipo_pessoa": "juridica",
          "classificacao_tributaria": "000001"
        }
      }
    }
  ],
  "transportation": {
    "transport_mode": "1",
    "freight_amount": 150.00,
    "carrier_info": {
      "cnpj": "11222333000144",
      "ie": "112223334",
      "name": "Transportadora Exemplo LTDA",
      "endereco": "Rod. BR-101, km 50",
      "city": "Santos",
      "uf": "SP",
      "cep": "11000000"
    },
    "vehicle_info": {
      "plate": "ABC1D23",
      "uf": "SP",
      "rntc": "12345"
    },
    "trailer_info": {
      "plate": "DEF4G56",
      "uf": "SP",
      "rntc": "67890"
    },
    "packages": [
      {
        "qty": 3,
        "gross_weight": 12.500,
        "net_weight": 11.000,
        "packaging_type": "CAIXA",
        "number": "001-003",
        "mark": "FRAGIL",
        "seals": ["LACRE001", "LACRE002"]
      }
    ],
    "transport_tax_retention_info": {
      "freight_service_amount": 150.00,
      "tax_base": 150.00,
      "tax_rate": 12.00,
      "cfop": "5932",
      "cep": "11000000"
    }
  },
  "pag_info": [
    {
      "payment_indicator": "1",
      "payment_method": "03",
      "payment_value": 7400.00,
      "card_info": {
        "integration_type": "1",
        "brand_code": "01",
        "acquirer_cnpj": "01234567000189",
        "authorization_code": "AUTH987654"
      }
    }
  ]
}

GET /api/invoice/get_list

NF-e 목록(페이지네이션)

회사의 NF-e를 페이지네이션으로 나열합니다. 매개변수는 쿼리 문자열로 전달됩니다(본문이 아님). 시간 필터는 선택 사항이지만, 사용 시 start_create_time과 end_create_time 둘 다 필요합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
page *	int	페이지 번호(≥ 1)
page_size *	int	페이지 크기(1–50)
start_create_time	long	Unix 타임스탬프(밀리초) — 시작(`end_create_time` 필수)
end_create_time	long	Unix 타임스탬프(밀리초) — 종료
status	string	상태로 필터링(값: `"Authorized"`, `"Canceled"`, `"Processing"`, `"Rejected"` 등)

* 필수 필드.

호출 예시

GET /api/invoice/get_list?page=1&page_size=20&status=Authorized

응답

        {
          "success": true,
          "data": {
            "list": [
              {
                "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
                "chave": "35210112345678901234567890123456789012345678",
                "status": "Authorized",
                "create": "2024-01-10T10:30:00Z",
                "issue_time": "2024-01-10T10:31:00Z"
              }
            ],
            "page": 1,
            "total": 142,
            "total_pages": 8
          }
        }

GET /api/invoice/get_detail

NF-e 세부 정보 조회

UUID로 특정 NF-e의 세부 정보를 반환합니다. XML URL, DANFE URL(전체, 간소화, 라벨) 및 메타데이터를 포함합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
uuid *	string	NF-e UUID

* 필수 필드.

호출 예시

GET /api/invoice/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9

응답

        {
          "success": true,
          "data": {
            "id": "order-2024-0001",
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234567890123456789012345678",
            "serie": 1,
            "number": 100,
            "status": "Authorized",
            "total_price": 300.00,
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": "https://oss.example.com/.../chave.pdf",
            "danfe_simples": "https://oss.example.com/.../chave_simplie.pdf",
            "danfe_etiqueta": "https://oss.example.com/.../chave_etiqueta.pdf",
            "create": "2024-01-10T10:30:00Z",
            "issue_time": "2024-01-10T10:31:00Z"
          }
        }

POST /api/invoice/refresh

송장 상태 갱신

SEFAZ에서 NF-e의 현재 상태를 조회하고 로컬 레코드를 갱신합니다. 발행이 처리 중이거나 비상 상태로 남아 있을 때 유용합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
uuid *	string	조회할 NF-e의 UUID

* 필수 필드.

페이로드 예시

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/cancel

송장 취소

승인된 NF-e를 취소합니다. SEFAZ에 보내는 사유는 고정되어 있습니다: "Erro no preenchimento da nota fiscal." — 페이로드로 구성할 수 없습니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
uuid *	string	취소할 NF-e의 UUID(`/api/invoice/create`에서 반환되는 내부 식별자)

* 필수 필드.

페이로드 예시

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

POST /api/invoice/invalid

번호 범위 무효화

승인되지 않은 NF-e 번호의 연속 범위를 무효화합니다(취소와 혼동하지 마세요 — 취소는 이미 승인된 송장에 적용됩니다). 이 작업은 SEFAZ에 기록되며 되돌릴 수 없습니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
modelo *	string	문서 모델: `"55"`=NF-e, `"65"`=NFC-e. (주의: 필드명은 `modelo`이며 `model`이 아닙니다)
ambiente *	string	`"1"`=운영, `"2"`=테스트
serie *	int	무효화할 번호의 시리즈
start_number *	int	범위 시작 번호
end_number *	int	범위 종료 번호
motivo *	string	무효화 사유 (SEFAZ 요구에 따라 최소 15자)

* 필수 필드.

페이로드 예시

        {
          "modelo": "55",
          "ambiente": "2",
          "serie": 1,
          "start_number": 100,
          "end_number": 105,
          "motivo": "Falha no sistema durante a emissao do lote"
        }

POST /api/invoice/get_danfe

NF-e의 DANFE(PDF) 가져오기

NF-e DANFE의 세 URL을 반환합니다: 전체 DANFE(PDF), 간소화된 DANFE PDF(영수증 형식), 간소화된 DANFE PNG(라벨 이미지). PDF는 승인된 XML로부터 요청 시 생성되어 OSS에 캐싱됩니다. 후속 호출에서 송장 상태가 변경되지 않은 경우 기존 캐시가 반환됩니다. 상태가 변경된 경우(예: 송장이 취소됨), PDF가 재생성됩니다.

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프(초, 5분 윈도우)

Body

필드	유형	설명
uuid ⚠	string	NF-e 내부 UUID (`/api/invoice/create`가 반환)
chave ⚠	string	NF-e 액세스 키(44자리)

⚠ uuid 또는 chave 중 하나는 필수.

페이로드 예시

                {
                  "uuid": "abc123-def456-..."
                }

응답

                {
                  "success": true,
                  "data": {
                    "danfe": "https://storage.../uid/dd-MM-yyyy/companyId/.pdf",
                    "danfe_simples": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.pdf",
                    "danfe_simples_png": "https://storage.../uid/cnpj/dd-MM-yyyy/_simplie.png"
                  }
                }

응답 필드

필드	유형	설명
danfe	string	전체 DANFE PDF의 URL(A4 형식)
danfe_simples	string	간소화된 DANFE PDF의 URL(영수증 형식)
danfe_simples_png	string	간소화된 DANFE PNG(라벨 이미지) URL

오류 응답

메시지	원인
uuid/chave不能为空	`uuid`도 `chave`도 전송되지 않음
发票不存在	토큰 사용자의 송장을 찾을 수 없음 또는 승인된 XML 누락
发票详情不存在	송장 세부사항(프로토콜 포함)을 찾을 수 없음
获取PDF失败:<사유>	XML로부터 PDF 생성 실패

POST /api/invoice/get_xml

XML/Excel 일괄 내보내기(비동기)

사용자의 송장에 대한 비동기 일괄 내보내기 작업을 시작하며 기간과 상태로 필터링합니다. Excel 스프레드시트(메타데이터만) 또는 XML 포함 ZIP 패키지를 생성할 수 있습니다. 첫 번째 호출은 작업을 만들고 status: "Processing"을 반환합니다. 동일한 매개변수의 후속 호출은 진행 상황을 반환하며 status: "Success"가 되면 url 필드에 다운로드 링크가 포함됩니다.

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body

필드	유형	설명
type *	string	출력 형식: `"excel"`(메타데이터 스프레드시트) 또는 기타 값(예: `"xml"`) - XML 포함 ZIP
status	string	송장 상태로 필터링(예: `"Success"`, `"Canceled"`, `"Voided"`). `type=excel`의 경우 내부적으로 소문자 처리
month	int	월(1–12). 제공된 경우 `start_create_time`/`end_create_time`을 대체; `America/Sao_Paulo` 타임존 및 현재 연도 사용(미래 월이면 전년도)
start_create_time	long	기간 시작(Unix 타임스탬프, 밀리초)
end_create_time	long	기간 종료(Unix 타임스탬프, 밀리초)

* 필수 필드.

페이로드 예시

                {
                  "type": "xml",
                  "status": "Success",
                  "month": 5
                }

응답 — 처리 중

                {
                  "success": true,
                  "data": {
                    "status": "Processing",
                    "progress_count": 120,
                    "total_count": 543,
                    "url": ""
                  }
                }

응답 — 완료

                {
                  "success": true,
                  "data": {
                    "status": "Success",
                    "progress_count": 543,
                    "total_count": 543,
                    "url": "https://storage.../exports/uid/.zip"
                  }
                }

응답 필드

필드	유형	설명
status	string	작업 실행 중에는 `"Processing"`, 파일이 준비되면 `"Success"`
progress_count	int	지금까지 처리된 송장 수
total_count	int	처리할 송장 총 수
url	string	최종 파일 다운로드 URL(`status = Processing` 동안은 빈 문자열)

멱등성: 작업은 매개변수 해시(uid + token + 기간 + status + type)로 중복 제거됩니다. 동일한 매개변수의 반복 호출은 새로운 실행을 트리거하지 않고 동일한 작업의 진행률을 반환합니다.

오류 응답

메시지	원인
发票类型字段不能为空	`type` 누락

POST /api/invoice/consultar_status

SEFAZ에서 NF-e/NFC-e 상태 조회

액세스 키(44자리)를 사용해 NfeConsultaProtocolo4 서비스를 통해 SEFAZ에서 직접 NF-e 또는 NFC-e의 현재 상태를 조회합니다. 토큰 회사가 발행한 자체 송장과 DistDFe로 캡처한 제3자 송장 모두 작동합니다. 모델(NF-e/NFC-e)은 키의 20-21 위치에서 자동으로 감지됩니다.

필수 헤더

헤더	유형	설명
token	string	회사 토큰(해당 인증서가 조회에 사용됨)
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프(초, 5분 윈도우)

Body

필드	유형	설명
chave *	string	액세스 키(44자리 숫자). 발행자 UF는 0-1 위치에서 추출, 모델은 20-21 위치에서 추출(`55`=NF-e, `65`=NFC-e).

* 필수 필드.

페이로드 예시

        {
          "chave": "35260512345678000199550010000000011000000018"
        }

응답

        {
          "success": true,
          "message": "Sucesso",
          "data": {
            "chave": "35260512345678000199550010000000011000000018",
            "status": "autorizada",
            "cstat": 100,
            "motivo": "Autorizado o uso da NF-e"
          }
        }

응답 필드

필드	유형	설명
chave	string	조회된 액세스 키
status	string	정규화된 상태(아래 표 참조)
cstat	int	SEFAZ의 원시 `cStat` 코드
motivo	string	SEFAZ의 원시 `xMotivo` 메시지

상태 매핑

`status`	SEFAZ cStat	의미
autorizada	`100`, `150`	사용 승인된 NF-e
cancelada	`101`, `151`	취소됨(`cStat=100`이라도 연결된 취소 이벤트가 있는 경우 반환)
denegada	`110`, `301`, `302`	SEFAZ에서 사용 거부
inutilizada	`102`	무효화된 번호(번호 범위)
nao_encontrada	`217`	NF-e가 SEFAZ 데이터베이스에 없음
desconhecido	기타	매핑되지 않은 cStat — 원시 `cstat`과 `motivo` 확인

오류 응답

메시지	원인
chave inválida: deve ter 44 dígitos	키 누락, 크기가 44가 아니거나 숫자가 아닌 문자 포함
empresa não possui certificado configurado	토큰 회사에 `cert_file`이 등록되어 있지 않음
SEFAZ retornou resposta vazia	SEFAZ가 응답을 반환하지 않음(타임아웃, 다운)
erro ao consultar SEFAZ: <세부정보>	서비스 호출 시 예외(잘못된 XML, 타임아웃, 만료된 인증서 등)

POST /api/category/create

세금 카테고리 생성

인증된 회사에 연결된 새 세금 카테고리(세금 템플릿)를 생성합니다. 각 카테고리는 ICMS, IPI, PIS, COFINS의 시나리오를 집계하며 선택적으로 IBS/CBS와 IS를 포함할 수 있습니다. 기존 카테고리를 편집하려면 /api/category/edit를 사용하세요.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body — 최상위

필드	타입	설명
descricao *	string	카테고리 설명
category_id	string	사용자 정의 ID. 생략 시 `"TF"` + 증분 번호로 자동 생성됨
disable_difal	boolean	이 카테고리의 DIFAL 계산 비활성화. 기본값: `false`
desconta_icms_pis_cofins	boolean	PIS/COFINS 과세표준에서 ICMS 공제 (과세표준 = vProd − vICMS). 기본값: `false`
icms[] *	array	ICMS 시나리오(구조는 아래)
ipi[] *	array	IPI 시나리오(구조는 아래)
pis[] *	array	PIS 시나리오(구조는 아래)
cofins[] *	array	COFINS 시나리오(구조는 아래)
ibs_cbs[]	array	IBS/CBS 시나리오 — 세제 개혁(구조는 아래)
is[]	array	IS 시나리오 — 선택세(구조는 아래)

Body — `icms[]`

필드	타입	설명
tipo_tributacao *	string	ICMS 과세 유형
cenario *	string	시나리오(예: `"saida_dentro_estado"`, `"saida_fora_estado"`, `"padrao"`)
tipo_pessoa *	string	`"fisica"` 또는 `"juridica"`
codigo_cfop *	string	CFOP
situacao_tributaria *	string	ICMS의 CST/CSOSN
nao_contribuinte	boolean	비납세 고객
aliquota_importacao	string	수입세율
aliquota_credito	decimal	크레딧 세율(Simples Nacional용 %)
aliquota_diferimento	decimal	이연 비율
aliquota_diferimentoFcp	string	FCP 이연(주의: 필드는 camelCase `diferimentoFcp`)
aliquota_reducao	decimal	ICMS 기준 감액 비율
aliquota_reducaoSt	decimal	ICMS-ST 기준 감액 비율(주의: `reducaoSt` camelCase)
motivo_desoneracao	string	ICMS 면세 사유 코드
motivo_desoneracaoSt	string	ICMS-ST 면세 사유 코드(주의: camelCase)
주(州)별 세율 — 선택
aliquota_mva[]	array	UF별 MVA — 항목: `{ estado, aliquota }`
aliquota_icms[]	array	UF별 ICMS 세율 — 항목: `{ estado, aliquota }`
aliquota_icms_st[]	array	UF별 ICMS-ST 세율 — 항목: `{ estado, aliquota }`
aliquota_fcp[]	array	UF별 FCP 세율 — 항목: `{ estado, aliquota }`
aliquota_fcp_st[]	array	UF별 FCP-ST 세율 — 항목: `{ estado, aliquota }`
beneficio_fiscal[]	array	UF별 세금 혜택 코드 — 항목: `{ estado, codigo }`

Body — `ipi[]`

필드	타입	설명
cenario *	string	시나리오
tipo_pessoa *	string	`"fisica"` 또는 `"juridica"`
situacao_tributaria *	string	IPI의 CST
codigo_enquadramento *	string	법적 분류 코드
aliquota *	string	IPI 세율

Body — `pis[]` 및 `cofins[]`(동일 구조)

필드	타입	설명
cenario *	string	시나리오
tipo_pessoa *	string	`"fisica"` 또는 `"juridica"`
situacao_tributaria *	string	PIS/COFINS의 CST
aliquota *	string	세율

Body — `ibs_cbs[]`(세제 개혁)

필드	타입	설명
cenario *	string	시나리오
tipo_pessoa *	string	`"fisica"` 또는 `"juridica"`
situacao_tributaria *	string	IBS/CBS의 CST
classificacao_tributaria *	string	세금 분류

Body — `is[]`(선택세)

필드	타입	설명
cenario *	string	시나리오
tipo_pessoa *	string	`"fisica"` 또는 `"juridica"`
situacao_tributaria *	string	IS의 CST
aliquota *	string	IS 세율

* 필수 필드.

최소 예시

        {
          "descricao": "Venda de mercadoria padrão",
          "icms": [{
            "tipo_tributacao": "normal",
            "cenario": "padrao",
            "tipo_pessoa": "juridica",
            "codigo_cfop": "5102",
            "situacao_tributaria": "00"
          }],
          "ipi":  [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "99", "codigo_enquadramento": "999", "aliquota": "0" }],
          "pis":  [{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "0.65" }],
          "cofins":[{ "cenario": "padrao", "tipo_pessoa": "juridica", "situacao_tributaria": "01", "aliquota": "3" }]
        }

응답

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

GET /api/category/get_detail

세금 카테고리 세부 정보

세금 카테고리의 전체 구성을 반환합니다: 모든 ICMS, IPI, PIS, COFINS, IBS/CBS 시나리오, UF별 배열(MVA, 세율, 세금 혜택)을 포함합니다.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
category_id *	string	세금 카테고리 ID

* 필수 필드.

호출 예시

GET /api/category/get_detail?category_id=TF123

응답

        {
          "success": true,
          "data": {
            "category_id": "TF123",
            "descricao": "Venda de mercadoria padrão",
            "disable_difal": false,
            "desconta_icms_pis_cofins": false,
            "icms": [{
              "tipo_tributacao": "normal",
              "cenario": "padrao",
              "tipo_pessoa": "juridica",
              "nao_contribuinte": false,
              "codigo_cfop": "5102",
              "situacao_tributaria": "00",
              "aliquota_importacao": "",
              "aliquota_credito": 0,
              "aliquota_reducao": 0,
              "aliquota_reducao_st": 0,
              "motivo_desoneracao": "",
              "motivo_desoneracao_st": "",
              "aliquota_icms": [{"estado":"SP","aliquota":18}]
            }],
            "ipi":    [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"99","codigo_enquadramento":"999","aliquota":"0"}],
            "pis":    [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"0.65"}],
            "cofins": [{"cenario":"padrao","tipo_pessoa":"juridica","situacao_tributaria":"01","aliquota":"3"}],
            "ibs_cbs":[]
          }
        }

GET /api/category/get_list

세금 카테고리 목록

인증된 회사의 세금 카테고리를 페이지네이션으로 나열합니다. 각 항목에 대해 category_id와 descricao만 반환합니다 — 전체 구성을 보려면 /api/category/get_detail을 사용하세요.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
page *	int	페이지 번호(≥ 1)
page_size *	int	페이지 크기(1–50)

* 필수 필드.

호출 예시

GET /api/category/get_list?page=1&page_size=20

응답

        {
          "success": true,
          "data": {
            "list": [
              { "category_id": "TF123", "descricao": "Venda de mercadoria padrão" },
              { "category_id": "TF124", "descricao": "Devolução de venda" }
            ],
            "page": 1,
            "total": 2,
            "total_pages": 1
          }
        }

POST /api/category/edit

세금 카테고리 편집

기존 세금 카테고리를 편집합니다. 본문은 /api/category/create와 동일하며, 유일한 차이점은 category_id가 필수이고 기존 카테고리와 일치해야 한다는 점입니다. Upsert는 icms, ipi, pis, cofins, ibs_cbs, is 배열을 완전히 대체합니다 — 업데이트된 모든 시나리오를 보내세요(시나리오 단위 병합 없음).

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

전체 본문 구조는 /api/category/create에 문서화되어 있습니다. 여기서는 category_id만 다르게 처리됩니다:

필드	타입	설명
category_id *	string	편집할 카테고리의 ID(존재해야 하며, 아니면 오류 반환)
descricao *	string	설명
icms[] *	array	ICMS 시나리오(완전 대체)
ipi[] *	array	IPI 시나리오
pis[] *	array	PIS 시나리오
cofins[] *	array	COFINS 시나리오
ibs_cbs[]	array	IBS/CBS 시나리오(선택)
is[]	array	IS 시나리오(선택)
disable_difal	boolean	기본값: `false`
desconta_icms_pis_cofins	boolean	기본값: `false`

* 필수 필드. 각 배열의 내부 필드(icms[].codigo_cfop 등)는 /api/category/create를 참조하세요.

응답

        {
          "success": true,
          "data": {
            "category_id": "TF123"
          }
        }

POST /api/category/delete

세금 카테고리 삭제

회사에서 세금 카테고리를 제거합니다. 되돌릴 수 없는 작업입니다. 이 카테고리에 연결된 제품은 삭제된 category_id를 계속 참조하므로 NFe 발행이 실패합니다 — 삭제 전에 제품을 업데이트하세요.

필수 헤더

헤더	타입	설명
token	string	회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
category_id *	string	삭제할 카테고리의 ID

* 필수 필드.

페이로드 예시

        {
          "category_id": "TF123"
        }

응답

        {
          "success": true
        }

POST /api/invoice/return

반품 NF-e 발행

원본 NF-e에서 반품 NF-e(모델 55, 용도 4)를 발행합니다. 두 가지 모드를 지원합니다: 전체 반품(uuid 또는 chave로 원본 인보이스 참조) 또는 부분/사용자 정의 반품(return_detail로 전체 본문 제공).

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body — 최상위 필드

필드	타입	설명
uuid	string	원본 NF-e의 UUID(`chave`가 없으면 필수. `return_detail` 모드에서는 사용하지 않음)
chave	string	원본 NF-e의 44자리 액세스 키(`return_detail` 모드에서는 필수. 간이 모드에서는 `uuid`의 대안)
cfop *	string	반품 CFOP(예: `"1202"`, `"1411"`, `"2202"`, `"5202"`, `"5411"`, `"6202"`)
natureza_operacao	string	거래 성격(예: "Devolução de venda"). 별칭 허용: `nature_of_operation`
return_detail	object	반품 NF-e의 전체 본문. `/api/invoice/create`와 동일한 구조이며, 한 가지 주의 사항: `return_detail.cliente` 내부 주소 번호 필드는 `number`(영어)이며 `numero`가 아닙니다. 생략 시 전체 반품으로 원본 NF-e를 복제합니다.

* 필수 필드. uuid 또는 chave도 필수입니다(둘 중 하나만).

예시 — 전체 반품

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "cfop": "5202",
          "natureza_operacao": "Devolução de venda"
        }

예시 — return_detail을 통한 부분 반품

        {
          "chave": "35210112345678901234567890123456789012345678",
          "cfop": "5202",
          "natureza_operacao": "Devolução parcial",
          "return_detail": {
            "nature_of_operation": "Devolução parcial",
            "transaction_type": "1",
            "model": "55",
            "issuance_type": "1",
            "ambiente": "2",
            "cliente": { "cnpj": "12345678000199", "name": "Fornecedor", "endereco": "...", "bairro": "...", "city": "...", "uf": "SP", "cep": "01001000" },
            "products": [ { "name": "...", "ncm": "...", "count": 1, "unit": "UN", "unit_price": 100, "total_price": 100, "category_id": "...", "origem": 0, "indicador_total": 1 } ]
          }
        }

code 완전한 송장 발행 예시

운송 포함 완전한 예시

{
  "nature_of_operation": "Venda de mercadoria",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "2",
  "ind_final": "0",
  "ind_pres": "1",
  "cliente": {
    "cnpj": "12345678000199",
    "ie": "123456789",
    "name": "Empresa Cliente Ltda",
    "endereco": "Rua Exemplo",
    "number": "123",
    "complemento": "Sala 45",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01234567",
    "telefone": "11999999999",
    "email": "contato@empresa.com"
  },
  "products": [
    {
      "codigo": "PROD001",
      "name": "Smartphone XYZ",
      "ncm": "85171210",
      "cest": "2804000",
      "count": 2,
      "unit": "UN",
      "unit_price": 1500.00,
      "total_price": 3000.00,
      "category_id": "SEU_CATEGORY_ID",
      "origem": "0",
      "indicador_total": "1"
    }
  ],
  "transportation": {
    "transport_mode": "0",
    "freight_amount": 30.00,
    "carrier_info": {
      "cnpj": "12345678000188",
      "name": "Transportadora Expressa",
      "endereco": "Rua da Transportadora",
      "city": "São Paulo",
      "uf": "SP"
    },
    "vehicle_info": {
      "plate": "ABC1234",
      "uf": "SP",
      "rntc": "123456"
    },
    "packages": [
      {
        "qty": 1,
        "packaging_type": "CX",
        "gross_weight": 2.500,
        "net_weight": 2.000
      }
    ]
  },
  "shipping_address": {
    "cnpj": "12345678000199",
    "name": "Remetente Ltda",
    "endereco": "Rua do Remetente",
    "number": "100",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01001000"
  },
  "delivery_address": {
    "cnpj": "98765432000111",
    "name": "Destinatário Ltda",
    "endereco": "Rua do Destinatário",
    "number": "200",
    "bairro": "Centro",
    "city": "Rio de Janeiro",
    "uf": "RJ",
    "cep": "20040020"
  },
  "pag_info": [
    {
      "payment_method": "03",
      "payment_indicator": "0",
      "card_info": {
        "integration_type": "1",
        "brand_code": "01"
      }
    }
  ],
  "informacoes_complementares": "Sem informações adicionais",
  "informacoes_fisco": "ICMS recolhido conforme legislação"
}

💡 INFORMATION: 이 예시에는 스크린샷에 언급된 모든 중요한 필드가 포함되어 있으며, 운송, 상세 세무 정보 및 결제를 포함합니다. 특정 필요에 따라 값을 조정하십시오.

수입 완전한 예제

{
  "id": "PED-IMP-001",
  "nature_of_operation": "Importacao para revenda",
  "transaction_type": "2",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "1",
  "finalidade": "1",
  "ind_final": "0",
  "ind_pres": "9",
  "cliente": {
    "name": "EXPORTADOR EXTERIOR CO LTD",
    "endereco": "Pudong District",
    "numero": "456",
    "city": "Shanghai",
    "id_estrangeiro": "CN-EXP-001",
    "c_pais": 1600,
    "x_pais": "CHINA"
  },
  "products": [
    {
      "name": "Fonte chaveada 12V 2A Quickfitting",
      "codigo": "123450000888",
      "ncm": "85044090",
      "count": 2,
      "unit": "PC",
      "unit_price": 0.25,
      "total_price": 0.50,
      "origem": 1,
      "indicador_total": "1",
      "category_id": "YOUR_CATEGORY_ID",
      "import_declarations": [
        {
          "nDI": "2312345678",
          "dDI": "2026-04-12",
          "xLocDesemb": "PORTO DE SANTOS",
          "UFDesemb": "SP",
          "dDesemb": "2026-04-15",
          "tpViaTransp": 1,
          "vAFRMM": 0.01,
          "tpIntermedio": 1,
          "cExportador": "EXP-CN-001",
          "additions": [
            {
              "nAdicao": 1,
              "nSeqAdic": 1,
              "cFabricante": "FAB-CN-001",
              "vDescDI": 0,
              "nDraw": ""
            }
          ]
        }
      ]
    },
    {
      "name": "Quick fitting MA",
      "codigo": "123450000157",
      "ncm": "85044090",
      "count": 2,
      "unit": "PC",
      "unit_price": 0.25,
      "total_price": 0.50,
      "origem": 1,
      "indicador_total": "1",
      "category_id": "YOUR_CATEGORY_ID",
      "ii": {
        "vBC": 0.50,
        "vDespAdu": 0.00,
        "vII": 0.00,
        "vIOF": 0.00
      },
      "import_declarations": [
        {
          "nDI": "2312345678",
          "dDI": "2026-04-12",
          "xLocDesemb": "PORTO DE SANTOS",
          "UFDesemb": "SP",
          "dDesemb": "2026-04-15",
          "tpViaTransp": 1,
          "vAFRMM": 1.00,
          "tpIntermedio": 1,
          "cExportador": "EXP-CN-001",
          "additions": [
            {
              "nAdicao": 1,
              "nSeqAdic": 2,
              "cFabricante": "FAB-CN-001",
              "vDescDI": 0,
              "nDraw": ""
            }
          ]
        }
      ]
    }
  ],
  "pag_info": [
    {
      "payment_method": "90",
      "payment_indicator": "0"
    }
  ]
}

💡 INFORMATION: NFe 수입 예시 (CFOP 3.xxx). 국내 NFe와의 차이점:

transaction_type: "2" — 입고(수입) 작업.
cliente는 cnpj/cpf/uf/cep 없음. id_estrangeiro, c_pais(BACEN 테이블 — 중국 = 1600), x_pais 사용.
category_id는 CFOP 3.xxx 및 수입과 호환되는 CST/CSOSN을 가진 세무 카테고리를 가리켜야 합니다.
제품의 origem = 1(외국 — 직수입) 또는 2(외국 — 국내 시장에서 구매).
ii 블록(수입세)은 CFOP가 3.xxx일 때 필수입니다. 값은 통관사가 발행한 DI에서 가져옵니다(vBC, vDespAdu, vII, vIOF). 테스트에서는 0이 될 수 있습니다.
import_declarations 블록(수입 신고)에는 통관 데이터가 포함됩니다: nDI, dDI, 통관 장소/UF/날짜, 운송 방식, 중개인, 수출자 및 추가 정보.
vAFRMM은 tpViaTransp = 1(해상)일 때 필수입니다.

vpn_key 인증

모든 요청에는 다음 헤더가 포함되어야 합니다:

헤더	타입	필수	설명
Content-Type	string	예	application/json;charset=utf-8
sign	string	예	요청 디지털 서명
timestamp	string	예	요청 UTC 타임스탬프
token	string	예	인증 토큰

참고: 기업 생성 및 기업 목록 조회에는 배포자 토큰(b2b_token)을 사용하십시오.

서명 알고리즘 (SIGN)

static string GetSign(string AppKey, string Path, string bodyString, string timestamp)
{
    string input = AppKey + Path + bodyString + timestamp;
    using (MD5 md5 = MD5.Create())
    {
        byte[] inputBytes = Encoding.UTF8.GetBytes(input);
        byte[] hashBytes = md5.ComputeHash(inputBytes);
        
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < hashBytes.Length; i++)
        {
            sb.Append(hashBytes[i].ToString("x2"));
        }
        return sb.ToString();
    }
}

중요: sign을 계산할 때 Path는 GET 요청의 쿼리 문자열을 포함합니다. 예시: /api/nfce/category/get_detail?category_id=TF123. POST 요청의 경우, Path는 경로만 해당됩니다 (예: /api/company/create).

percent Detailed Tax Parameters

scale_balance ICMS Parameters

Taxation Scenario

default output_outside_state output_inside_state input_outside_state input_inside_state

Tax Situation (CST)

00: Fully taxed

02: Tax exempt

10: Taxed with ICMS collection

20: With reduced calculation base

30: Exempt or not taxed

40: Exempt

41: Not taxed

50: Suspension

51: Deferral

60: ICMS previously collected

70: Reduction and collection

90: Others

pie_chart PIS/COFINS Parameters

Taxation Scenario

default output_outside_state output_inside_state input_outside_state input_inside_state

Tax Situation (CST)

01: Taxable Operation (normal rate)

02: Taxable Operation (differentiated rate)

03: Taxable Operation (exempt)

04: Taxable Operation (suspension)

05: Taxable Operation (ST)

06: Taxable Operation (zero rate)

07: Contribution Exempt Operation

08: Operation without Contribution Incidence

09: Operation with Contribution Suspension

49: Other Output Operations

50: Credit right (own operations)

51: Credit right (acquisitions)

52: Credit posting

53: Debit posting

54: Credit posting (extemporaneous)

55: Debit posting (extemporaneous)

56: Presumed Credit

60: Presumed Credit (acquisitions)

61: Presumed Credit (import)

62: Presumed Credit (rural activity)

63: Presumed Credit (others)

64: Presumed Credit (non-generator)

65: Presumed Credit (substitution)

66: Presumed Credit (substitution)

67: Presumed Credit (export)

70: Acquisition Operation without Credit Right

71: Acquisition Operation with Exemption

72: Acquisition Operation with Suspension

73: Acquisition Operation at Zero Rate

74: Acquisition Operation without Incidence

75: Acquisition Operation by Substitution

98: Other Input Operations

99: Other Operations

💡 INFORMATION: The tipo_pessoa fields accept values fisica (individual) or juridica (legal entity). For PIS/COFINS, the aliquota field must be formatted as string with two decimal places (ex: "1.65").

credit_card Payment Parameters

Payment Indicator

`0`	현금
`1`	Credit

Payment Methods

`01`	현금
`02`	수표
`03`	신용카드
`04`	직불카드
`05`	매장 크레딧
`10`	식사 바우처
`11`	식품 바우처
`12`	Gift Voucher
`13`	연료 바우처
`15`	은행 송금표
`90`	No Payment
`99`	Others

Card Brands

`01`	Visa
`02`	Mastercard
`03`	American Express
`04`	Sorocred
`05`	Diners Club
`06`	Elo
`07`	Hipercard
`08`	Aura
`09`	Cabal
`99`	Others

bug_report XML Troubleshooting

warning Rejection 225 - XML Schema Failure

취소, XML 다운로드, 번호 무효화 시도 시 발생합니다, or manifest an NF-e that was not successfully registered in SEFAZ database.

NF-e가 승인되었는지 확인 (상태 "Authorized")

Re-issue NF-e if not authorized

Invalidate number if not used

lightbulb SEFAZ Online Validation

Use official validator to identify XML problems:


                  https://www.sefaz.rs.gov.br/nfe/nfe-val.aspx

Common problems: Incomplete address, invalid NCM, incorrect value formatting, missing required fields.

error SEFAZ Error Codes

코드	설명	Solution
`217`	Issue date too delayed	Issue in contingency or regularize
`404`	Recipient CNPJ/CPF invalid	Verify customer document
`563`	CFOP not allowed for operation	Review operation CFOP

기타 엔드포인트

4. List Categories: GET /api/category/get_list

5. Category Details: GET /api/category/get_detail

6. Edit Category: POST /api/category/edit

7. Delete Category: POST /api/category/delete

CFOP Examples (Fiscal Operation Code):

5102: Sale of merchandise acquired from third parties - within state

6102: Sale of merchandise acquired from third parties - to another state

6108: Sale of merchandise acquired from third parties - to another state (individual)

1000: Merchandise entry

speed

제한 및 요청 제한

API usage policies

Limits by Plan

Free Plan	100 requests/day
Basic Plan	1,000 requests/day
Pro Plan	10,000 requests/day
Enterprise Plan	Customized

Values for `transport_mode`:

0: Freight contracted by Sender (CIF)

1: Freight contracted by Recipient (FOB)

2: Freight contracted by Third Party

3: Own Transport by Sender

4: Own Transport by Recipient

9: No Transportation Occurrence

CFOP Examples (Fiscal Operation Code):

5102: Sale of merchandise acquired from third parties - within state

6102: Sale of merchandise acquired from third parties - to another state

6108: Sale of merchandise acquired from third parties - to another state (individual)

1000: Merchandise entry

assessment NFe Reports

Generate detailed reports of issued Electronic Invoices (NF-e), with filters by period, status and operation type. Ideal for fiscal monitoring, audits and management control.

1. Issued Invoices Report

GET /api/invoice/report

요청 매개변수 (쿼리)

매개변수	필수	타입	설명
company_id	예	String	Company ID
start_date	예	Date	Period start date (YYYY-MM-DD)
end_date	예	Date	Period end date (YYYY-MM-DD)
status	아니오	String	Filter by status: `AUTHORIZED`, `CANCELED`, `DENIED`, `ALL` (default)
model	아니오	String	Document model: `nfe`, `nfce`, `all` (default)
format	아니오	String	Output format: `json` (default), `csv`, `pdf`
page	아니오	Integer	Page number (default: 1)
per_page	아니오	Integer	Records per page (default: 50, max: 200)

요청 예시

GET /api/invoice/report?company_id=comp_123456&start_date=2024-01-01&end_date=2024-01-31&status=AUTHORIZED&format=json

응답 예시

{
  "success": true,
  "data": {
    "summary": {
      "total_invoices": 152,
      "total_value": 458320.50,
      "authorized": 145,
      "canceled": 5,
      "denied": 2
    },
    "invoices": [
      {
        "invoice_id": "nf_789012",
        "number": 1045,
        "series": 1,
        "access_key": "35210112345678901234...",
        "status": "AUTHORIZED",
        "issue_date": "2024-01-10T10:30:00Z",
        "total_value": 3000.00,
        "customer_name": "Empresa Cliente Ltda",
        "customer_document": "12.345.678/0001-99",
        "nature_of_operation": "VENDA",
        "model": "nfe"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total_pages": 4,
      "total_records": 152
    }
  }
}

2. Period Summary Report

GET /api/invoice/report/summary

Returns a consolidated summary of fiscal operations grouped by month, with totals for value, quantity and taxes.

요청 매개변수 (쿼리)

매개변수	필수	타입	설명
company_id	예	String	Company ID
year	예	Integer	Reference year (e.g.: 2024)
group_by	아니오	String	Group by: `month` (default), `week`, `day`

응답 예시

{
  "success": true,
  "data": {
    "company_id": "comp_123456",
    "year": 2024,
    "periods": [
      {
        "period": "2024-01",
        "total_invoices": 152,
        "total_value": 458320.50,
        "total_tax": 82497.69,
        "authorized": 145,
        "canceled": 5,
        "denied": 2
      },
      {
        "period": "2024-02",
        "total_invoices": 178,
        "total_value": 523180.75,
        "total_tax": 94172.54,
        "authorized": 170,
        "canceled": 6,
        "denied": 2
      }
    ]
  }
}

3. Export Report

POST /api/invoice/report/export

Generates and exports the full report in PDF or CSV format. The export is processed asynchronously and returns a download URL when completed.

페이로드 요청

{
  "company_id": "comp_123456",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "format": "pdf",
  "status": "ALL",
  "include_details": true,
  "include_taxes": true
}

응답 예시

{
  "success": true,
  "message": "Report processing",
  "data": {
    "report_id": "rpt_abc123",
    "status": "processing",
    "estimated_time": "30s",
    "callback_url": "https://api.tffiscal.com/v1/report/status/rpt_abc123"
  }
}

Response After Processing

{
  "success": true,
  "data": {
    "report_id": "rpt_abc123",
    "status": "completed",
    "download_url": "https://storage.tffiscal.com/reports/rpt_abc123.pdf",
    "expires_at": "2024-02-01T23:59:59Z",
    "file_size": "2.4 MB"
  }
}

💡 TIP: Use the format=csv parameter to integrate data with ERP systems or spreadsheets. The PDF format is ideal for presentations and fiscal audits.

⚠️ WARNING: The maximum allowed period per query is 12 months. For full annual reports, use the export endpoint (/report/export). Queries with large data volumes may take a few seconds to process.

vpn_key TF Hub 글로벌 인증

모든 TF Hub API는 통합 인증 시스템을 사용합니다.

필수 헤더

헤더	Value	설명
X-API-Key	String	API key provided in dashboard
X-Timestamp	Unix Timestamp	Request timestamp in milliseconds
X-Signature	String	HMAC-SHA256 signature

point_of_sale NFC-e — Electronic Consumer Invoice

Base URL (운영 환경)

https://api.tffiscal.com

인증

Headers: sign, timestamp, token

요구사항

유효한 A1 디지털 인증서 (.pfx 또는 .p12)
CSC (납세자 보안 코드)
CSC ID (SEFAZ의 CSC 식별자)

NFC-e (model 65) is the electronic fiscal document for retail sales to end consumers, either in-person or via home delivery. It replaces the old fiscal coupon (ECF).

NFC-e Characteristics:

Always an intrastate operation — no DIFAL
No IPI (Industrialized Product Tax)
Recipient is optional for in-person sales (ind_pres: "1")
Recipient is required for home delivery (ind_pres: "4")
Requires CSC (납세자 보안 코드) for QR Code generation

인증

모든 NFC-e 엔드포인트는 메인 API와 동일한 인증을 사용합니다:

헤더	타입	설명
token	string	Company token (obtained during registration)
sign	string	MD5 signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 유효)

중요: When calculating the sign, the path includes the query string for GET requests. 예시: /api/nfce/category/get_detail?category_id=TF123. For POST requests, the path is just the route (e.g., /api/nfce/company/create).

compare_arrows NFe vs NFC-e — What Changes for Integrators?

If you have already integrated with NFe (model 55), integrating NFC-e (model 65) is very similar. Below are the key differences you need to know.

apartment Company Registration

Aspect	NFe `/api/company/create`	NFC-e `/api/nfce/company/create`
Basic fields	cnpj, name, alias, ie, invoice_type, address, 디지털 인증서	Same as NFe — same required fields
CSC	Not used	필수 — `csc_id` and `csc` (obtained from the SEFAZ portal)
Series / Numbering	`serie` and `number`	`serie_nfce` and `number_nfce` — independent numbering from NFe
Returned token	Same `token` — if the company already exists, the NFC-e fields are added automatically

Tip: If the company was already registered for NFe, just call /api/nfce/company/create with the same CNPJ. The system will recognize the existing company and add the NFC-e fields (CSC, series, numbering). The token remains the same.

receipt_long Invoice Emission

Aspect	NFe `/api/invoice/create`	NFC-e `/api/nfce/create`
Recipient	Always required (CNPJ/CPF, name, full address)	선택 사항 대면 판매의 경우; 필수 택배 배송의 경우에만 (`ind_pres: "4"`)
Presence indicator	Not used	필수 — `ind_pres`: `"1"` in-person, `"4"` home delivery
Taxes calculated	ICMS, PIS, COFINS, IPI, DIFAL (interstate)	ICMS, PIS, COFINS — no IPI, no DIFAL (always intrastate)
CFOP	Varies (5xxx intrastate, 6xxx interstate)	Always 5xxx (intrastate) — e.g., `5102`
Payment	선택 사항	필수 — `pag_info` with payment method (cash, PIX, card, etc.)
Product fields	Same — same structure (codigo, name, ncm, count, unit, unit_price, total_price, category_id, cfop, origem)
취소	24-hour window	30-minute window (varies by state)
DANFE	A4 PDF	Thermal receipt (80mm roll) with QR Code

Summary: If you have already integrated NFe, to integrate NFC-e you just need to:

Register the company's CSC (/api/nfce/company/create)
Switch the emission endpoint to /api/nfce/create
Add ind_pres and pag_info to the payload
Remove IPI/DIFAL data (if present)

POST /api/nfce/company/create

NFC-e용 회사 등록

NFC-e 발급용 회사를 등록(또는 업데이트)합니다. 회사명, IE, 주소 및 기타 데이터는 CNPJ에서 SintegraWS를 통해 자동 추출됩니다. CNPJ가 이미 사용자에게 존재하면 NFC-e 필드가 업데이트되고 기존 회사가 반환됩니다.

필수 헤더

헤더	타입	설명
token	string	디스트리뷰터 토큰(b2b)
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
cnpj *	string	발행 회사 CNPJ
cert_file *	string	A1 디지털 인증서(.pfx 또는 .p12)의 HTTPS URL
cert_pwd *	string	인증서 비밀번호
csc_id *	string	SEFAZ의 CSC(납세자 보안 코드) ID
csc *	string	CSC 토큰(SEFAZ와 공유하는 비밀)
serie_nfce	int	NFC-e 시리즈
number_nfce	int	NFC-e 초기 번호
telefone	string	회사 전화번호

* 필수 필드. 기타 데이터(이름, IE, 주소 등)는 CNPJ에서 SintegraWS를 통해 자동 추출됩니다.

페이로드 예시

        {
          "cnpj": "12345678000199",
          "cert_file": "https://example.com/cert.pfx",
          "cert_pwd": "senha_do_certificado",
          "csc_id": "000001",
          "csc": "ABCDEF0123456789",
          "serie_nfce": 1,
          "number_nfce": 1,
          "telefone": "11999999999"
        }

응답

        {
          "success": true,
          "message": "NFC-e용 회사가 등록되었습니다",
          "data": {
            "company_id": "comp_789012",
            "token": "eyJhbGciOiJIUzI1NiIs..."
          }
        }

POST /api/nfce/company/update

NFC-e 회사 데이터 업데이트

token 헤더로 식별되는 NFC-e 회사를 업데이트합니다. Body의 모든 필드는 선택 사항입니다 — 변경하려는 필드만 보내세요. cep를 업데이트하면 시스템이 자동으로 stateCode와 ibge를 해결합니다. cert_file과 cert_pwd가 함께 오면 인증서는 저장 전에 검증됩니다.

필수 헤더

헤더	타입	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body(모든 필드 선택 — 최소 1개 전송)

필드	타입	설명
식별
name	string	회사명
alias	string	상호
ie	string	주(州) 등록 번호
invoice_type	string	세제
email	string	이메일
telefone	string	전화번호
주소
cep	string	우편번호(`stateCode`와 `ibge` 자동 업데이트)
address	string	도로명 주소
house_number	string	번호
complemento	string	보충
town	string	지구
city	string	도시
state	string	UF
NFC-e
csc_id	string	CSC ID
csc	string	CSC 토큰
serie_nfce	int	시리즈
number_nfce	int	다음 번호
cert_file	string	새 A1 인증서(.pfx 또는 .p12)의 HTTPS URL
cert_pwd	string	인증서 비밀번호

Body의 최소 1개 필드가 필수입니다. CNPJ는 변경할 수 없습니다.

페이로드 예시

        {
          "alias": "Centro Store - Branch 02",
          "telefone": "11988888888",
          "serie_nfce": 2,
          "number_nfce": 1
        }

응답

        {
          "success": true,
          "message": "NFC-e 회사가 성공적으로 업데이트되었습니다"
        }

POST /api/nfce/company/get

NFC-e 회사 조회

token 헤더로 식별되는 NFC-e 회사 데이터를 반환합니다. 주의: 메서드는 POST이지만 본문 필드는 필요하지 않습니다 — 회사는 토큰만으로 식별됩니다.

필수 헤더

헤더	타입	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

비어 있음. {}를 보낼 수 있습니다.

응답

        {
          "success": true,
          "data": {
            "company_id": "comp_789012",
            "cnpj": "12345678000199",
            "name": "Empresa Exemplo LTDA",
            "alias": "Centro Store",
            "ie": "123456789",
            "invoice_type": "simples_nacional",
            "email": "contact@company.com",
            "telefone": "11999999999",
            "cep": "01001000",
            "address": "Example Street",
            "house_number": "100",
            "complemento": "Room 5",
            "town": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "state_code": "SP",
            "cert_file": "https://example.com/cert.pfx",
            "csc_id": "000001",
            "csc": "ABCDEF0123456789",
            "serie_nfce": 1,
            "number_nfce": 42
          }
        }

NFC-e Fiscal Category Management

Fiscal categories define the tax rules applied to products when issuing NFC-e. Unlike NFe, NFC-e only operates with intrastate sales, so the structure is simplified: a single object per tax type, without the need for multiple scenarios.

참고: NFC-e categories are stored separately from NFe categories. Each category includes ICMS, PIS, COFINS, and IBS/CBS settings. All endpoints in this section require the token, sign, and timestamp headers.

POST /api/nfce/category/create

NFC-e 세무 카테고리 생성

NFC-e 세무 카테고리를 생성합니다. 각 카테고리는 단일 시나리오(내부 출고)를 가지며 ICMS, PIS, COFINS, IBS/CBS에 플랫 객체를 사용합니다(NFC-e는 카테고리당 여러 시나리오를 허용하지 않으므로 배열이 아닙니다). IPI는 없습니다.

필수 헤더

헤더	유형	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body (루트)

필드	유형	설명
descricao *	string	카테고리 설명
codigo_cfop *	string	CFOP 코드 (예: 5102, 5405)
icms *	object	ICMS 설정 (플랫 객체)
pis *	object	PIS 설정 (플랫 객체)
cofins *	object	COFINS 설정 (플랫 객체)
ibs_cbs	object	IBS/CBS 설정 (세제 개혁, 선택사항)

icms

필드	유형	설명
situacao_tributaria *	string	CST/CSOSN (예: 102, 500)
aliquota_reducao	decimal	과세표준 감면 비율
motivo_desoneracao	string	면제 사유 코드
aliquota_icms	array	주별 세율: `[{ "estado": "SP", "aliquota": 18.00 }]`
aliquota_fcp	array	주별 FCP: `[{ "estado": "SP", "aliquota": 0.00 }]`
beneficio_fiscal	array	주별 세제 혜택: `[{ "estado": "SP", "codigo": "SP800001" }]`

pis / cofins

필드	유형	설명
situacao_tributaria *	string	PIS/COFINS CST
aliquota *	string	퍼센트 세율 (예: "0.00", "1.65", "7.60")

ibs_cbs (선택사항)

필드	유형	설명
situacao_tributaria *	string	IBS/CBS CST
classificacao_tributaria *	string	세무 분류 코드

* 필수 필드.

페이로드 예시

        {
          "descricao": "Bebidas não alcoólicas",
          "codigo_cfop": "5102",
          "icms": {
            "situacao_tributaria": "102",
            "aliquota_icms": [
              { "estado": "SP", "aliquota": 18.00 }
            ]
          },
          "pis": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "cofins": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "ibs_cbs": {
            "situacao_tributaria": "000",
            "classificacao_tributaria": "000001"
          }
        }

응답

        {
          "success": true,
          "data": {
            "category_id": "TF00001"
          }
        }

GET /api/nfce/category/get_detail

NFC-e 세무 카테고리 상세 조회

NFC-e 세무 카테고리의 전체 데이터(설명, CFOP, ICMS, PIS, COFINS, IBS/CBS)를 반환합니다.

필수 헤더

헤더	유형	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

쿼리 문자열

필드	유형	설명
category_id *	string	NFC-e 카테고리 ID

* 필수 필드.

요청 예시

GET /api/nfce/category/get_detail?category_id=TF00001

응답

        {
          "success": true,
          "data": {
            "category_id": "TF00001",
            "descricao": "Bebidas não alcoólicas",
            "codigo_cfop": "5102",
            "icms": {
              "situacao_tributaria": "102",
              "aliquota_icms": [
                { "estado": "SP", "aliquota": 18.00 }
              ],
              "aliquota_fcp": [
                { "estado": "SP", "aliquota": 0.00 }
              ],
              "beneficio_fiscal": [
                { "estado": "SP", "codigo": "SP800001" }
              ]
            },
            "pis": {
              "situacao_tributaria": "99",
              "aliquota": "0.00"
            },
            "cofins": {
              "situacao_tributaria": "99",
              "aliquota": "0.00"
            },
            "ibs_cbs": {
              "situacao_tributaria": "000",
              "classificacao_tributaria": "000001"
            }
          }
        }

GET /api/nfce/category/get_list

NFC-e 세무 카테고리 목록

인증된 회사에 등록된 NFC-e 세무 카테고리의 페이지네이션 목록을 반환합니다.

필수 헤더

헤더	유형	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

쿼리 문자열

필드	유형	설명
page *	int	페이지 번호 (최소 1)
page_size *	int	페이지당 항목 수 (1~50)

* 필수 필드.

요청 예시

GET /api/nfce/category/get_list?page=1&page_size=20

응답

        {
          "success": true,
          "data": {
            "list": [
              { "category_id": "TF00001", "descricao": "Bebidas não alcoólicas" },
              { "category_id": "TF00002", "descricao": "Alimentos industrializados" }
            ],
            "page": 1,
            "total": 2,
            "total_pages": 1
          }
        }

POST /api/nfce/category/edit

NFC-e 세무 카테고리 편집

참고: /api/nfce/category/create 엔드포인트와 동일한 구조이며, 추가 필수 필드 category_id가 있습니다. icms, pis, cofins, ibs_cbs 필드는 완전히 대체됩니다(병합되지 않음).

필수 헤더

헤더	유형	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

추가 필드

필드	유형	설명
category_id *	string	편집할 카테고리 ID

* 필수 필드.

페이로드 예시

        {
          "category_id": "TF00001",
          "descricao": "Bebidas não alcoólicas — atualizado",
          "codigo_cfop": "5102",
          "icms": {
            "situacao_tributaria": "102",
            "aliquota_icms": [
              { "estado": "SP", "aliquota": 18.00 }
            ]
          },
          "pis": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "cofins": {
            "situacao_tributaria": "99",
            "aliquota": "0.00"
          },
          "ibs_cbs": {
            "situacao_tributaria": "000",
            "classificacao_tributaria": "000001"
          }
        }

응답

        {
          "success": true,
          "data": {
            "category_id": "TF00001"
          }
        }

POST /api/nfce/category/delete

NFC-e 세금 카테고리 삭제

NFC-e 세금 카테고리를 제거합니다. 되돌릴 수 없는 작업입니다. 이 카테고리에 연결된 제품은 삭제된 category_id를 계속 참조하므로 — 먼저 업데이트하세요.

필수 헤더

헤더	타입	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
category_id *	string	삭제할 NFC-e 카테고리의 ID

* 필수 필드.

페이로드 예시

        {
          "category_id": "TF123"
        }

응답

        {
          "success": true
        }

POST /api/nfce/create

NFC-e 발행

NFC-e(모델 65, 항상 주 내 출고, 운송 없음)를 발행합니다. NFe 엔드포인트와의 주요 차이점: 소비자 객체는 client(cliente가 아님); 주소 번호는 client.number; 소비자는 선택사항; impostos.ipi, shipping_address, delivery_address, transportation는 존재하지 않음. pag_info의 금액 필드 이름은 amount.

필수 헤더

헤더	유형	설명
token	string	NFC-e 회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프(초, 5분 윈도우)

Body (루트)

필드	유형	설명
nature_of_operation *	string	거래 성격 (예: "상품 판매")
issuance_type *	string	발행 유형: "1" (정상), "9" (NFC-e 오프라인 비상)
ambiente *	string	"1" 운영, "2" 호몰로게이션
products *	array	상품 목록 (아래 참조)
id	string	외부 식별자
ind_pres	string	구매자 임석: "1" 대면(기본값), "4" 가정 배송, "5" 시설 외 대면, "9" 해당 없음
ind_intermed	string	"0" 중개자 없음, "1" 마켓플레이스. `ind_pres` = 2, 3, 4일 때 필수
total_discount_amount	decimal	송장 총 할인
troco	decimal	거스름돈 금액
seguro	decimal	보험 금액
outras_despesas	decimal	기타 부대 비용
informacoes_complementares	string	소비자 보충 정보
informacoes_fisco	string	세무 당국 관심 정보
client	object	소비자 데이터 (선택사항 — 아래 표 참조)
pag_info	array	결제 (기본값: 현금 — 아래 표 참조)

client (선택사항)

소비자가 식별된 경우에만 입력하세요. CPF 또는 CNPJ는 숫자만 전송해야 합니다.

필드	유형	설명
cpf	string	CPF (개인 설정)
cnpj	string	CNPJ (법인)
ie	string	주 등록 번호
name	string	이름 / 법인명
endereco	string	도로명
number	string	주소 번호 (주의: NFe는 `numero`를 사용)
complemento	string	보충
bairro	string	동네
city	string	도시
uf	string	주 (CEP 제공 시 검증됨)
cep	string	우편번호 (숫자만)
telefone	string	전화
email	string	이메일

products[] (각 항목)

필드	유형	설명
name *	string	상품명 (CJK 문자는 제거됨)
ncm *	string	NCM (8자리)
count *	decimal	수량
unit *	string	상업 단위 (예: "UN", "KG")
unit_price *	decimal	단가
total_price *	decimal	항목 총액
origem *	int	상품 원산지 (0..8)
indicador_total *	int	1 = 송장 총액 구성; 0 = 구성하지 않음
category_id ⚠	string	NFC-e 세무 카테고리 ID (`impostos` 미전송 시 필수)
impostos ⚠	object	수동 세금 (`category_id`의 대안, IPI 없음)
tax_info ⚠	object	`impostos`의 별칭 (동일한 구조). `impostos` 누락 시에만 사용
codigo	string	내부 상품 코드
cest	string	CEST
gtin	string	상업 GTIN/EAN
gtin_tributavel	string	과세 GTIN
discount_price	decimal	항목 할인
nItemPed	int	구매 주문 품목 (I61). 루트의 `id`에서 가져온 `xPed`가 참조하는 주문 내 항목 일련번호. 유효 범위: 1–999999. 기본값: 생략.

pag_info[] (각 항목)

필드	유형	설명
payment_indicator *	string	"0" 현금, "1" 신용
payment_method *	string	결제 방법 (01=현금, 03=신용카드, 04=직불카드, 17=PIX, 99=기타 등)
amount	decimal	이 방법으로 결제된 금액
card_info.integration_type	string	"1" 통합, "2" 비통합 (카드 03/04 시 필수)
card_info.brand_code	string	카드 브랜드 (카드 03/04 시 필수)
card_info.acquirer_cnpj	string	결제 대행사 CNPJ
card_info.authorization_code	string	승인 코드

* 필수 필드. ⚠ category_id, impostos, tax_info 중 하나는 필수.

간소화된 예시

{
  "nature_of_operation": "Venda de mercadoria",
  "issuance_type": "1",
  "ambiente": "2",
  "ind_pres": "1",
  "client": {
    "cpf": "12345678909",
    "name": "Consumidor Final"
  },
  "products": [
    {
      "name": "Refrigerante 2L",
      "ncm": "22021000",
      "count": 2,
      "unit": "UN",
      "unit_price": 10.50,
      "total_price": 21.00,
      "origem": 0,
      "indicador_total": 1,
      "category_id": "TF00001"
    }
  ],
  "pag_info": [
    {
      "payment_indicator": "0",
      "payment_method": "17",
      "amount": 21.00
    }
  ]
}

완전한 예시 (모든 필드)

{
  "id": "PEDIDO-2026-0001",
  "nature_of_operation": "Venda de mercadoria",
  "issuance_type": "1",
  "ambiente": "2",
  "ind_pres": "1",
  "ind_intermed": "0",
  "total_discount_amount": 0.00,
  "troco": 0.00,
  "seguro": 0.00,
  "outras_despesas": 0.00,
  "informacoes_complementares": "Pedido entregue na loja",
  "informacoes_fisco": "ICMS recolhido conforme legislação",
  "client": {
    "cpf": "12345678909",
    "cnpj": "",
    "ie": "",
    "name": "Consumidor Final",
    "endereco": "Rua das Flores",
    "number": "100",
    "complemento": "Sala 5",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01001000",
    "telefone": "11999998888",
    "email": "cliente@exemplo.com"
  },
  "products": [
    {
      "codigo": "PROD001",
      "name": "Refrigerante 2L",
      "ncm": "22021000",
      "cest": "0300100",
      "gtin": "7891234567890",
      "gtin_tributavel": "7891234567890",
      "count": 2,
      "unit": "UN",
      "unit_price": 10.50,
      "total_price": 21.00,
      "discount_price": 0.00,
      "origem": 0,
      "indicador_total": 1,
      "category_id": "TF00001",
      "nItemPed": 1
    },
    {
      "codigo": "PROD002",
      "name": "Salgadinho 100g",
      "ncm": "19053100",
      "count": 1,
      "unit": "UN",
      "unit_price": 8.00,
      "total_price": 8.00,
      "origem": 0,
      "indicador_total": 1,
      "impostos": {
        "icms": {
          "codigo_cfop": "5102",
          "situacao_tributaria": "102",
          "industria": "",
          "tipo_pessoa": "juridica"
        },
        "pis": {
          "situacao_tributaria": "99",
          "aliquota": "0.00",
          "tipo_pessoa": "juridica"
        },
        "cofins": {
          "situacao_tributaria": "99",
          "aliquota": "0.00",
          "tipo_pessoa": "juridica"
        },
        "ibs_cbs": {
          "situacao_tributaria": "000",
          "tipo_pessoa": "juridica",
          "classificacao_tributaria": "000001"
        }
      }
    }
  ],
  "pag_info": [
    {
      "payment_indicator": "0",
      "payment_method": "03",
      "amount": 24.00,
      "card_info": {
        "integration_type": "1",
        "brand_code": "01",
        "acquirer_cnpj": "01234567000189",
        "authorization_code": "AUTH123456"
      }
    }
  ]
}

응답

        {
          "success": true,
          "data": {
            "uuid": "abc123...",
            "chave": "35..."
          }
        }

POST /api/nfce/cancel

NFC-e 취소

승인된 NFC-e를 취소합니다. NFe와 달리 취소 사유는 클라이언트가 제공하고 SEFAZ로 전달됩니다. SEFAZ 취소 창은 짧습니다(보통 승인 후 15-30분).

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
chave *	string	NFC-e의 44자리 액세스 키(주의: 다른 엔드포인트의 `uuid`가 아니라 `chave`입니다)
motivo *	string	취소 사유(SEFAZ 요구에 따라 최소 15자)

* 필수 필드.

페이로드 예시

        {
          "chave": "35210112345678901234650010000000051234567890",
          "motivo": "Cancelamento por erro de operacao do caixa"
        }

GET /api/nfce/get_detail

NFC-e 세부 정보 조회

UUID로 특정 NFC-e의 세부 정보를 반환합니다. XML과 DANFE(영수증) URL, 제공된 경우 고객 데이터를 포함합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명(path에 쿼리 문자열 포함)
timestamp	string	초 단위 Unix 타임스탬프

쿼리 문자열

매개변수	타입	설명
uuid *	string	NFC-e UUID

* 필수 필드.

호출 예시

GET /api/nfce/get_detail?uuid=65f8b9a1c2d3e4f5a6b7c8d9

응답

        {
          "success": true,
          "data": {
            "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
            "chave": "35210112345678901234650010000000051234567890",
            "serie": 1,
            "number": 5,
            "status": "Authorized",
            "modelo": "nfce",
            "total_price": 145.90,
            "nprot": "135210000123456",
            "motivo": "",
            "xml": "https://oss.example.com/.../chave.xml",
            "danfe": "https://oss.example.com/.../chave_nfce.pdf",
            "client_cpf": "12345678909",
            "client_cnpj": "",
            "client_name": "Cliente",
            "create": "2024-01-10T10:30:00Z",
            "issue_time": "2024-01-10T10:31:00Z"
          }
        }

POST /api/nfce/get_danfe

NFC-e DANFE(영수증) 생성/가져오기

NFC-e DANFE(전자 재정 영수증)의 PDF URL을 반환합니다. SEFAZ 조회용 QR 코드를 포함합니다. 필요에 따라 생성되며 해시(액세스 키 + 상태)로 캐시됩니다. 반복 호출 시 기존 URL을 반환합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
uuid *	string	NFC-e UUID(주의: 여기서는 `uuid`이며, `cancel`의 `chave`와 다릅니다)

* 필수 필드.

페이로드 예시

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

응답

        {
          "success": true,
          "data": {
            "danfe": "https://oss.example.com/.../chave_nfce.pdf"
          }
        }

code NFC-e Complete Examples

Example 1 — In-Person Sale (no recipient)

{
  "nature_of_operation": "Venda de mercadoria",
  "ambiente": "2",
  "ind_pres": "1",
  "products": [
    {
      "codigo": "001",
      "name": "Refrigerante 350ml",
      "ncm": "22021000",
      "count": 3,
      "unit": "UN",
      "unit_price": 5.50,
      "total_price": 16.50,
      "category_id": "BEVERAGES_DEFAULT",
      "origem": "0",
      "indicador_total": "1",
      "cfop": "5102"
    }
  ],
  "pag_info": [
    { "payment_indicator": "0", "payment_method": "17" }
  ]
}

Example 2 — Home Delivery (with recipient)

{
  "nature_of_operation": "Venda de mercadoria",
  "ambiente": "2",
  "ind_pres": "4",
  "client": {
    "cpf": "12345678900",
    "name": "Maria Silva",
    "endereco": "Rua das Flores",
    "number": "456",
    "bairro": "Jardim Primavera",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "04567000"
  },
  "products": [
    {
      "codigo": "PIZZA01",
      "name": "Pizza Grande Marguerita",
      "ncm": "19059090",
      "count": 1,
      "unit": "UN",
      "unit_price": 45.90,
      "total_price": 45.90,
      "category_id": "FOOD",
      "origem": "0",
      "indicador_total": "1",
      "cfop": "5102"
    }
  ],
  "pag_info": [
    { "payment_indicator": "0", "payment_method": "03" }
  ],
  "frete": 8.00,
  "informacoes_complementares": "Entrega em até 40 minutos"
}

tune NFe Adjustment / Supplementary

Supplementary NFe and Adjustment NFe are invoices issued to correct tax values of an already authorized invoice. Unlike CC-e, which only corrects registration data, these invoices allow changing tax amounts, quantities, and prices.

Supplementary NFe (finalidade = 2):

Used to add values that were reported lower than correct in the original invoice
Price supplement, quantity, or tax amount
Example: issued invoice with 12% ICMS but the correct rate was 18% — issue supplementary with the difference

Adjustment NFe (finalidade = 3):

Used for various tax adjustments provided by legislation
Inventory adjustment, credit transfer, tax regularization
Example: ICMS adjustment by assessment, credit transfer between branches

중요:

Both are new invoices — they generate a new access key and new number
Must reference the original invoice via the ref_nfe_chave field (44-digit key)
The original invoice must be authorized
Each consumes 1 credit (same as a regular issuance)

인증

NFe 발행과 동일한 엔드포인트 및 인증을 사용합니다:

헤더	타입	설명
token	string	Company token (obtained during registration)
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 유효)

description NFS-e - 전자 서비스 청구서

NFS-e API는 전자 서비스 청구서의 발행, 취소 및 조회를 가능하게 합니다. 시스템은 자동으로 기업의 시/군을 감지하고 올바른 API로 라우팅합니다:

상파울루 (SP) - Nota Fiscal Paulistana (SOAP)를 통한 발행
기타 시/군 - 국가 API (ADN/SEFIN)를 통한 발행

통합자는 어떤 API를 사용할지 걱정할 필요가 없습니다. 데이터만 보내면 기업에 등록된 시/군의 IBGE 코드에 따라 자동으로 라우팅됩니다.

엔드포인트	메서드	설명
`/api/nfse/create`	POST	NFS-e 발행
`/api/nfse/cancel`	POST	NFS-e 취소
`/api/nfse/get_danfse`	POST	DANFSE 받기 (PDF)
`/api/nfse/get_xml`	POST	XML 다운로드

POST /api/nfs/company/create

NFS-e 발행을 위한 회사 등록

NFS-e 발행을 위해 회사를 등록(또는 업데이트)합니다. CNPJ가 사용자에 대해 이미 존재하는 경우, NFS-e 필드와 인증서만 업데이트됩니다. 그렇지 않으면 새 회사가 생성되고 전용 토큰이 반환됩니다. 경로 주의: /api/nfs/...("e" 없음), 다른 NFS-e 엔드포인트와 다릅니다.

필수 헤더

헤더	유형	설명
token	string	인티그레이터 B2B 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body

필드	유형	설명
cnpj *	string	회사 CNPJ (숫자만)
name *	string	법인명
cep *	string	우편번호 (숫자만)
address *	string	도로명
house_number *	string	주소 번호
town *	string	동네
city *	string	도시
state *	string	주 (2자리, 예: "SP")
cert_file *	string	A1 디지털 인증서(.pfx)의 URL
cert_pwd *	string	디지털 인증서 비밀번호
im *	string	시 등록 번호 (Inscrição Municipal)
codigo_municipio_nfse *	string	발행 도시의 IBGE 코드
codigo_servico_nfse *	string	기본 서비스 코드 (LC 116)
alias	string	상호
ie	string	주 등록 번호
invoice_type	string	세제 체계
unit	string	단위 / 지점
email	string	연락처 이메일
telefone	string	전화
complemento	string	주소 보충
cnae_nfse	string	기본 활동 CNAE
serie_nfse	int	NFS-e 초기 시리즈
number_nfse	int	NFS-e 초기 번호
regime_especial_tributacao	int	특별 세제 코드
optante_simples_nacional	bool	Simples Nacional 가입

* 필수 필드.

페이로드 예시

        {
          "cnpj": "43649380000100",
          "name": "Empresa Exemplo LTDA",
          "alias": "예시",
          "ie": "ISENTO",
          "invoice_type": "simples_nacional",
          "email": "contact@example.com",
          "telefone": "11999999999",
          "cep": "03027020",
          "address": "예시 거리",
          "house_number": "86",
          "complemento": "2층",
          "town": "중앙",
          "city": "São Paulo",
          "state": "SP",
          "cert_file": "https://storage.example.com/cert.pfx",
          "cert_pwd": "senha-do-certificado",
          "im": "12345678",
          "codigo_municipio_nfse": "3550308",
          "codigo_servico_nfse": "07498",
          "cnae_nfse": "6201501",
          "serie_nfse": 1,
          "number_nfse": 1,
          "regime_especial_tributacao": 0,
          "optante_simples_nacional": true
        }

응답

        {
          "success": true,
          "message": "Empresa cadastrada para NFS-e",
          "data": {
            "company_id": 12345,
            "token": "token-dedicado-da-empresa"
          }
        }

참고: 반환된 token은 다른 NFS-e 호출(/api/nfse/create, /cancel, /get_danfse, /get_xml)에서 사용해야 합니다. 회사가 이미 존재하는 경우 메시지는 "Empresa atualizada para NFS-e"이며 반환되는 토큰은 기존 토큰입니다.

POST /api/nfse/create

NFS-e 발행

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 유효)

페이로드

{
  "ambiente": "1",
  "id": "REF-001",
  "descricao_servico": "Desenvolvimento de sistemas",
  "valor_servico": 10000.00,
  "aliquota_iss": 2.90,
  "iss_retido": false,
  "codigo_servico": "",
  "cnae": "",
  "valor_deducoes": 0,
  "desconto_incondicionado": 0,
  "desconto_condicionado": 0,
  "valor_iss": 0,
  "valor_pis": 0,
  "valor_cofins": 0,
  "valor_inss": 0,
  "valor_ir": 0,
  "valor_csll": 0,
  "tomador": {
    "cnpj": "43649380000100",
    "cpf": "",
    "name": "EMPRESA TOMADORA LTDA",
    "email": "contato@empresa.com",
    "telefone": "11999999999",
    "inscricao_municipal": "",
    "cep": "03027020",
    "endereco": "Rua Exemplo",
    "numero": "86",
    "complemento": "Andar 2",
    "bairro": "Centro",
    "city": "Sao Paulo",
    "uf": "SP",
    "codigo_municipio": "3550308"
  }
}

주요 필드

필드	타입	설명
ambiente	string	`"1"` = 운영환경, `"2"` = 테스트환경
id	string	외부 참조 ID (선택)
descricao_servico	string	서비스 설명 (필수)
valor_servico	decimal	서비스 총 금액 (R$) (필수)
aliquota_iss	decimal	ISS 세율 (%) (예: 2.90)
iss_retido	boolean	`false` = 원천징수 없음, `true` = 지급자가 원천징수
valor_iss	decimal	ISS 값 오버라이드. 0보다 크면 자동 계산 (base_calculo × aliquota_iss ÷ 100)을 대체. 기본값: 자동 계산
codigo_servico	string	서비스 코드. 비어있으면 기업 기본값 사용
cnae	string	CNAE. 비어있으면 기업 기본값 사용
tomador	object	서비스 수령자 데이터 (필수)

지급자 필드

필드	타입	설명
cnpj	string	지급자 CNPJ (숫자만)
cpf	string	지급자 CPF (cnpj 또는 cpf 사용)
name	string	이름/회사명 (필수)
email	string	지급자 이메일
telefone	string	전화번호
cep	string	우편번호 (필수)
endereco	string	주소 (필수)
numero	string	번지 (필수)
complemento	string	보충 주소
bairro	string	지역구 (필수)
city	string	도시
uf	string	주 (2자리)
codigo_municipio	string	IBGE 시/군 코드

성공 응답

{
  "success": true,
  "data": {
    "_id": "661234abcdef...",
    "uuid": "guid-unico",
    "status": "autorizada",
    "nfse": "48",
    "serie": 1,
    "chave": "Z685RI9C",
    "codigoVerificacao": "Z685RI9C",
    "modelo": "nfse",
    "tipoEmissao": "paulistana",
    "danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
  }
}

POST /api/nfse/cancel

NFS-e 취소

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프 (초)

페이로드

{
  "chave": "Z685RI9C",
  "motivo": "Cancelamento da NFS-e por erro na emissao"
}

필드

필드	타입	설명
chave	string	NFS-e 검증 코드 (필수)
motivo	string	취소 사유 (필수, 최소 15자)

성공 응답

{
  "success": true,
  "message": "Nota de servico cancelada com sucesso"
}

POST /api/nfse/get_danfse

DANFSE 받기 (PDF)

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프 (초)

페이로드

{
  "chave": "Z685RI9C"
}

필드

필드	타입	설명
chave	string	NFS-e 검증 코드 (필수)

응답

{
  "success": true,
  "data": {
    "danfse": "https://nfe.prefeitura.sp.gov.br/contribuinte/notaprintpdf.aspx?..."
  }
}

참고: Paulistana (SP)의 경우 시청의 PDF 직접 URL을 반환합니다. 국가 API의 경우 base64 형식의 PDF를 반환합니다.

POST /api/nfse/get_xml

NFS-e XML 다운로드

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프 (초)

페이로드

{
  "chave": "Z685RI9C"
}

필드

필드	타입	설명
chave	string	NFS-e 검증 코드 (필수)

응답

{
  "success": true,
  "data": {
    "dpsXml": "<PedidoEnvioRPS>...</PedidoEnvioRPS>",
    "nfseXml": "<RetornoEnvioRPS>...</RetornoEnvioRPS>"
  }
}

dpsXml: 시청/ADN에 전송된 XML. nfseXml: 발행 결과가 포함된 반환 XML.

POST /api/invoice/create

보충 NFe 발행 (finalidade = 2)

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 유효)

페이로드

{
  "finalidade": "2",
  "ref_nfe_chave": "NFE_KEY_HERE",
  "nature_of_operation": "Price supplement",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "1",
  "ind_final": "1",
  "ind_pres": "2",
  "cliente": {
    "cpf": "264.438.800-72",
    "name": "Nome do Destinatário",
    "endereco": "Rua Example",
    "number": "100",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01310100",
    "indIEDest": "9"
  },
  "products": [
    {
      "codigo": "001",
      "name": "Complemento de valor - Produto X",
      "ncm": "82100090",
      "count": 1,
      "unit": "UN",
      "unit_price": 5.00,
      "total_price": 5.00,
      "category_id": "YOUR_CATEGORY_ID",
      "origem": "0",
      "indicador_total": "1",
      "cfop": "5102"
    }
  ],
  "pag_info": [
    {
      "payment_method": "90",
      "payment_indicator": "0"
    }
  ]
}

Specific Fields

필드	타입	설명
finalidade	string	`"2"` for Supplementary (required)
ref_nfe_chave	string	Access key of the original invoice — 44 digits (required)

참고: The remaining fields follow the same pattern as the /api/invoice/create endpoint for regular issuance. See the NFe issuance documentation for details on all fields.

Payment: In supplementary invoices, payment is usually "90" (No Payment) since it is only a supplement of tax values.

성공 응답

{
  "success": true,
  "data": {
    "uuid": "a1b2c3d4-e5f6-...",
    "chave": "35260312345678000195550010000004051234567890",
    "status": "Success",
    "motivo": "Autorizado o uso da NF-e",
    "nfe": 405,
    "serie": 1,
    "danfe": "https://storage.../danfe.pdf",
    "xml": "https://storage.../xml.xml"
  }
}

POST /api/invoice/create

조정 NFe 발행 (finalidade = 3)

필수 헤더

헤더	타입	설명
token	string	기업 토큰
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 유효)

페이로드

{
  "finalidade": "3",
  "ref_nfe_chave": "NFE_KEY_HERE",
  "nature_of_operation": "Tax adjustment",
  "transaction_type": "1",
  "model": "55",
  "issuance_type": "1",
  "ambiente": "1",
  "ind_final": "1",
  "ind_pres": "2",
  "cliente": {
    "cpf": "264.438.800-72",
    "name": "Nome do Destinatário",
    "endereco": "Rua Example",
    "number": "100",
    "bairro": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "cep": "01310100",
    "indIEDest": "9"
  },
  "products": [
    {
      "codigo": "001",
      "name": "Ajuste fiscal - Regularização",
      "ncm": "82100090",
      "count": 1,
      "unit": "UN",
      "unit_price": 0.01,
      "total_price": 0.01,
      "category_id": "YOUR_CATEGORY_ID",
      "origem": "0",
      "indicador_total": "1",
      "cfop": "5949"
    }
  ],
  "pag_info": [
    {
      "payment_method": "90",
      "payment_indicator": "0"
    }
  ]
}

Specific Fields

필드	타입	설명
finalidade	string	`"3"` for Adjustment (required)
ref_nfe_chave	string	Access key of the original invoice — 44 digits (required)

Available finalidade values:

Value	설명
1	Normal (default)
2	Supplementary
3	Adjustment
4	Return

Difference between Supplementary and Adjustment:

Supplementary (2): Supplements values from the original invoice (price, tax, quantity reported lower than correct)
Adjustment (3): Tax adjustments provided by legislation (regularization, credit transfer, inventory adjustment)

edit_note CC-e — Electronic Correction Letter

The CC-e (Electronic Correction Letter) is an event linked to the NF-e that allows correcting information in an already authorized invoice, without changing tax values. Regulated by Ajuste SINIEF 01/07.

What can be corrected via CC-e:

Recipient or issuer address
Recipient company name (without changing CNPJ/CPF)
Fiscal operation code (CFOP), as long as it does not change the nature of taxes
Product description
Additional data and supplementary information

What CANNOT be corrected via CC-e:

Tax values (tax base, rate, tax amount)
Product quantity and value
Issuer or recipient CNPJ/CPF
Data that changes tax calculations

Rules:

Only invoices with authorized (Success) status can receive CC-e
Correction text must be between 15 and 1000 characters
Up to 20 CC-e can be issued for the same invoice
Each CC-e consumes 1 credit

인증

모든 CC-e 엔드포인트는 메인 API와 동일한 인증을 사용합니다:

헤더	타입	설명
token	string	Company token (obtained during registration)
sign	string	MD5 Signature: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 유효)

POST /api/invoice/cce/send

정정장(CC-e) 전송

이미 승인된 NF-e의 데이터를 정정하기 위해 SEFAZ에 CC-e(이벤트 110110)를 전송합니다. 시퀀스 번호(nSeqEvento)는 자동으로 계산됩니다 — 보내지 마세요. 비재무 데이터만 정정할 수 있습니다(금액, CNPJ, IE 등은 정정할 수 없습니다).

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
uuid	string	NF-e UUID(`chave`가 없으면 필수)
chave	string	NF-e의 44자리 액세스 키(`uuid`가 없으면 필수)
correcao *	string	정정 텍스트(SEFAZ 제한: 15–1000자)

* 필수 필드. uuid 또는 chave 중 적어도 하나도 필수입니다.

페이로드 예시

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9",
          "correcao": "Corrigir nome do destinatario para Empresa XYZ LTDA"
        }

응답

        {
          "success": true,
          "data": {
            "nProt": "135210000123456",
            "nSeqEvento": 1,
            "xml": "https://oss.example.com/.../cce.xml"
          }
        }

POST /api/invoice/cce/get_list

NF-e의 CC-e 목록

특정 NF-e에 발급된 모든 CC-e(정정장)를 최신순으로 반환합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
uuid	string	NF-e UUID(`chave`가 없으면 필수)
chave	string	NF-e의 44자리 액세스 키(`uuid`가 없으면 필수)

uuid 또는 chave 중 적어도 하나가 필수입니다.

페이로드 예시

        {
          "uuid": "65f8b9a1c2d3e4f5a6b7c8d9"
        }

응답

        {
          "success": true,
          "data": {
            "items": [
              {
                "id": "65fa1b2c3d4e5f6a7b8c9d0e",
                "detail": "Corrigir nome do destinatario para Empresa XYZ LTDA",
                "nProt": "135210000123456",
                "nSeqEvento": 1,
                "date": "15/01/2024 14:30:00",
                "pdfUrl": "https://oss.example.com/.../cce_seq1.pdf",
                "xmlUrl": "https://oss.example.com/.../cce.xml"
              }
            ],
            "total": 1
          }
        }

POST /api/invoice/cce/download_pdf

CC-e PDF 다운로드

CC-e PDF URL을 반환합니다. PDF는 첫 호출 시 필요에 따라 생성되어(송장 XML + CC-e XML에서 렌더링) OSS에 저장됩니다. 이후 호출에서는 기존 URL을 반환합니다.

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
cce_id *	string	`/api/invoice/cce/get_list`의 `id` 필드로 반환되는 CC-e ID(ObjectId)

* 필수 필드.

페이로드 예시

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

응답

        {
          "success": true,
          "data": {
            "url": "https://oss.example.com/.../cce_seq1.pdf"
          }
        }

POST /api/invoice/cce/download_xml

CC-e XML 다운로드

서명된 CC-e XML URL을 반환합니다(SEFAZ에 제출된 후 이미 OSS에 저장됨).

필수 헤더

헤더	타입	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	초 단위 Unix 타임스탬프

Body

필드	타입	설명
cce_id *	string	`/api/invoice/cce/get_list`의 `id` 필드로 반환되는 CC-e ID(ObjectId)

* 필수 필드.

페이로드 예시

        {
          "cce_id": "65fa1b2c3d4e5f6a7b8c9d0e"
        }

응답

        {
          "success": true,
          "data": {
            "url": "https://oss.example.com/.../cce.xml"
          }
        }

how_to_reg 수신자 표명 (Manifestação do Destinatário)

수신자 표명은 NF-e의 수신자가 자사 CNPJ 앞으로 발행된 송장에 대해 공식적으로 의사를 표명할 수 있도록 합니다. SEFAZ에서 정의한 4가지 이벤트 유형이 있으며, 각각 고유한 법적 의미를 가집니다.

이벤트 유형

코드	이름	의미	사유
210210	거래 인지	수신자가 NF-e의 존재를 인지했으나 아직 확인하거나 거부하지 않았습니다. 일반적으로 가장 먼저 보내는 이벤트로, DistDFe를 통해 전체 XML을 다운로드하기 위한 전제 조건입니다.	필수 아님
210200	거래 확인	수신자가 거래가 발생했고 상품/서비스를 수령했음을 확인합니다. 최종 이벤트로 수령을 증명합니다.	필수 아님
210220	거래 부인	수신자가 거래를 인정하지 않음을 선언합니다 (사기 의심, CNPJ 도용 등).	필수 (15-255자)
210240	거래 미실행	수신자가 거래를 인지하지만 실제로는 이루어지지 않았음을 선언합니다 (반품, 수령 거부 등).	필수 (15-255자)

순서 규칙: 인지 (210210)를 전송한 후 확인 (210200) 또는 부인 (210220) 또는 미실행 (210240)을 전송할 수 있습니다. 확인/부인/미실행은 최종 상태이며 덮어쓸 수 없습니다.

주의: cnpj 필드에 전송하는 CNPJ는 NF-e의 수신자(표명자)여야 하며, 사용하는 토큰에 연결된 시스템에 등록되어 있어야 합니다. 그렇지 않으면 SEFAZ가 "이벤트 작성자가 NF-e 수신자와 다릅니다"라는 거부를 반환합니다.

cStat 반환 코드

cStat	의미
135	✅ 이벤트가 성공적으로 등록됨
573	✅ 이벤트 중복 — 이미 등록됨 (성공으로 처리)
236	❌ 잘못된 액세스 키
491	❌ 표명이 이미 등록됨 — 최종 상태를 덮어쓸 수 없음
596	❌ 수신자 CNPJ가 제공된 값과 다름
656	❌ 부적절한 사용 (속도 제한)

POST /api/invoice/manifest

수신자 표명 이벤트 전송

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

{
  "chave": "35260514200166000187550010000000011000000018",
  "cnpj": "14200166000187",
  "tipo_evento": 210210,
  "justificativa": "Operação reconhecida pelo destinatário"
}

필드

필드	유형	필수	설명
chave	string	예	NF-e 액세스 키 — 44자리
cnpj	string	예	수신자 CNPJ (표명자) — 14자리, 형식 없음. 시스템에 등록되어 있어야 함
tipo_evento	int	예	이벤트 코드: `210200`, `210210`, `210220` 또는 `210240`
justificativa	string	조건부	`210220`과 `210240`에 필수. 15-255자 사이. `210200`과 `210210`에서는 무시됨

시퀀스 (nSeqEvento): 자동으로 계산됩니다. 동일한 조합 (cnpj + chave + tipo_evento)의 경우 호출마다 증가됩니다 — 따라서 중복 시 cStat: 573이 반환되며 오류 없이 저장됩니다.

성공 응답

{
  "success": true,
  "message": "data",
  "data": {
    "id": "67341a8f5d4e1f2a3b4c5d6e",
    "chave": "35260514200166000187550010000000011000000018",
    "cnpj": "14200166000187",
    "tipo_evento": 210210,
    "desc_evento": "Ciencia da Operacao",
    "nProt": "135260000123456",
    "cStat": 135,
    "xMotivo": "Evento registrado e vinculado a NF-e",
    "nSeqEvento": 1,
    "xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
  }
}

응답 필드

필드	유형	설명
id	string	표명 레코드의 내부 ObjectId (`/get_xml`에서 사용)
chave	string	표명된 NF-e의 액세스 키
cnpj	string	표명한 수신자 CNPJ
tipo_evento	int	전송된 이벤트 코드 (210200/210210/210220/210240)
desc_evento	string	이벤트 텍스트 설명 (SEFAZ 원문)
nProt	string	SEFAZ 프로토콜 번호 — 이벤트 영수증
cStat	int	SEFAZ 상태 코드. `135` = 등록됨, `573` = 중복 (또한 수락됨)
xMotivo	string	SEFAZ 설명 메시지
nSeqEvento	int	자동으로 할당된 이벤트 시퀀스
xml_url	string	OSS에 저장된 procEvento XML (서명 및 프로토콜 포함)의 공개 URL

예시 — 사유와 함께 부인 (210220)

{
  "chave": "35260514200166000187550010000000011000000018",
  "cnpj": "14200166000187",
  "tipo_evento": 210220,
  "justificativa": "Operação desconhecida pelo destinatário, sem pedido vinculado ao fornecedor informado"
}

POST /api/invoice/manifest/list

전송된 표명 목록 (이력)

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

{
  "cnpj": "14200166000187",
  "chave": "",
  "start_create_time": "01/05/2026",
  "end_create_time": "31/05/2026",
  "page": 1,
  "page_size": 20
}

필드

필드	유형	필수	설명
cnpj	string	아니오	수신자 CNPJ로 필터링. 생략 시 사용자의 모든 CNPJ에서 검색
chave	string	아니오	특정 NF-e 키 (44자리)로 필터링
start_create_time	string/long	아니오	시작 날짜. 다음 형식 허용: `"dd/MM/yyyy"`, `"yyyy-MM-dd"`, `"dd/MM/yyyy HH:mm:ss"` 또는 Unix 타임스탬프 (초). 날짜만 있을 경우 00:00:00 UTC로 간주
end_create_time	string/long	아니오	종료 날짜. 같은 형식. 날짜만 있을 경우 23:59:59.999 UTC로 간주
page	int	아니오	페이지 번호 (기본 `1`)
page_size	int	아니오	페이지당 항목 수 (기본 `20`, 최대 `100`)

성공 응답

{
  "success": true,
  "message": "成功",
  "data": {
    "total": 2,
    "page": 1,
    "page_size": 20,
    "list": [
      {
        "id": "67341a8f5d4e1f2a3b4c5d6e",
        "chave": "35260514200166000187550010000000011000000018",
        "cnpj": "14200166000187",
        "tipo_evento": 210210,
        "desc_evento": "Ciencia da Operacao",
        "justificativa": "Operação reconhecida pelo destinatário",
        "nProt": "135260000123456",
        "nSeqEvento": 1,
        "cStat": 135,
        "xMotivo": "Evento registrado e vinculado a NF-e",
        "xml_url": "https://storage.../...210210_1.xml",
        "create": "2026-05-13 14:25:33"
      }
    ]
  }
}

응답 필드

필드	유형	설명
total	int	필터 조건과 일치하는 레코드 총 개수 (페이지네이션 무관)
page	int	반환된 현재 페이지
page_size	int	반환된 페이지 크기
list[].id	string	레코드의 내부 ObjectId
list[].chave	string	표명된 NF-e의 액세스 키
list[].cnpj	string	표명한 수신자 CNPJ
list[].tipo_evento	int	이벤트 코드 (210200/210210/210220/210240)
list[].desc_evento	string	이벤트 텍스트 설명
list[].justificativa	string	전송된 사유 (210220/210240에서만 채워짐)
list[].nProt	string	이벤트의 SEFAZ 프로토콜 번호
list[].nSeqEvento	int	이벤트 시퀀스
list[].cStat	int	SEFAZ 상태 코드
list[].xMotivo	string	SEFAZ 설명 메시지
list[].xml_url	string	OSS의 procEvento XML 공개 URL
list[].create	string	레코드의 UTC 타임스탬프 (형식 `yyyy-MM-dd HH:mm:ss`)

정렬: 레코드는 최신순(생성일 내림차순)으로 반환됩니다.

POST /api/invoice/manifest/get_xml

특정 표명의 XML URL 가져오기

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

{
  "id": "67341a8f5d4e1f2a3b4c5d6e"
}

필드

필드	유형	필수	설명
id	string	예	표명의 ObjectId — `/manifest` 또는 `/manifest/list`에서 반환됨

성공 응답

{
  "success": true,
  "message": "data",
  "data": {
    "id": "67341a8f5d4e1f2a3b4c5d6e",
    "chave": "35260514200166000187550010000000011000000018",
    "tipo_evento": 210210,
    "xml_url": "https://storage.../manifestacao/13-05-2026/352605...210210_1.xml"
  }
}

일반적인 오류

메시지	원인
id inválido	값이 유효한 ObjectId가 아님
manifestação não encontrada	ObjectId는 존재하지만 토큰의 사용자에 속하지 않거나 삭제됨

cloud_download DistDFe 캡처 — 수신 NFe

SEFAZ (국가 환경)의 NFeDistribuicaoDFe 서비스를 통해 자사 CNPJ로 도착한 NFe와 이벤트를 조회하고 다운로드할 수 있습니다. 캡처는 NSU(고유 순차 번호)별 증분 방식으로 — 각 호출은 아직 캡처되지 않은 항목만 다운로드합니다.

반환되는 문서 유형

doc_type	설명	내용
resNFe	NFe 요약	기본 메타데이터 (키, 금액, 발행자, 상태). 인지 이벤트가 전송되기 전에 도착 — 상품/세금이 포함되지 않음
procNFe	전체 승인된 NFe	완전한 NF-e XML (상품, 세금, 운송 등 포함). 수신자가 해당 키에 대해 인지 (210210)를 전송한 후에만 사용 가능
resEvento	이벤트 요약	이벤트 메타데이터 (키, 유형, 시퀀스, 사유)
procEvento	전체 이벤트	완전한 이벤트 XML (CC-e, 취소, 다른 수신자의 표명 등)

권장 워크플로:

/received/sync 호출 — 모든 새 문서 다운로드
/received/list에서 doc_type: "resNFe"로 필터링하여 인지하지 않은 송장 확인
관심있는 각 키에 대해 /invoice/manifest를 tipo_evento: 210210으로 호출
/received/sync 다시 호출 — 이제 SEFAZ가 표명된 키의 procNFe(전체 XML) 반환
/received/get_xml로 XML URL을 가져와 처리

SEFAZ 속도 제한: SEFAZ는 CNPJ당 시간당 최대 1회의 DistDFe 호출을 허용합니다. 초과 시 cStat: 656(부적절한 사용)이 반환됩니다. 검증 환경에서는 더 관대한 규칙이 적용됩니다.

DistDFe 반환 cStat 코드

cStat	의미
137	✅ 문서 없음 (정상 루프 종료)
138	✅ 문서 발견 — 루프 계속
656	❌ 부적절한 사용 — 1시간 대기 후 재시도
252	❌ 제공된 환경과 다름 (프로덕션 vs 검증)
280	❌ 인증서 만료 또는 무효

POST /api/invoice/received/sync

동기화 — SEFAZ에서 DistDFe를 통해 새로운 NFe/이벤트 다운로드

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

{
  "cnpj": "26638419000167",
  "max_iterations": 50
}

필드

필드	유형	필수	설명
cnpj	string	예	수신자 회사 CNPJ — 14자리, 형식 없음. 토큰에 연결된 시스템에 등록되어 있어야 함
max_iterations	int	아니오	실행당 최대 SEFAZ 호출 수. 각 호출은 최대 50개 문서 다운로드. 기본 `50` (≈2,500개 문서), 최대 `200`

작동 방식:

(uid + cnpj)에 대해 저장된 최신 ultNSU 읽기
cStat ≠ 138 또는 max_iterations에 도달할 때까지 SEFAZ 호출 루프
반환된 XML (gzip) 압축 해제
각 문서를 w_invoice_received에 저장하고 XML을 OSS에 업로드
w_invoice_received_sync의 ultNSU와 maxNSU 업데이트
(uid + cnpj + nsu)로 중복 제거 — 반복 호출 시 중복되지 않음

성공 응답

{
  "success": true,
  "message": "data",
  "data": {
    "cnpj": "26638419000167",
    "uf": "SP",
    "initial_nsu": 0,
    "ult_nsu": 2323,
    "max_nsu": 2323,
    "pending": 0,
    "iterations": 8,
    "last_cstat": 137,
    "last_motivo": "Nenhum documento localizado",
    "stats": {
      "resNFe": 3,
      "procNFe": 4,
      "resEvento": 336,
      "procEvento": 5,
      "skipped": 0
    }
  }
}

응답 필드

필드	유형	설명
cnpj	string	조회된 수신자 CNPJ
uf	string	조회에 사용된 수신자 주(州) 코드
initial_nsu	long	시작 NSU — 이 실행 전에 처리된 마지막 NSU
ult_nsu	long	동기화 후 새로운 마지막 NSU
max_nsu	long	조회 시점에 SEFAZ AN에서 사용 가능한 최대 NSU
pending	long	여전히 보류 중인 문서 (`max_nsu - ult_nsu`). > 0이면 `/sync`를 다시 호출하여 나머지 다운로드
iterations	int	이 실행에서 수행된 SEFAZ 호출 수
last_cstat	int	SEFAZ가 반환한 마지막 cStat. `137`은 정상 종료, `656`은 속도 제한
last_motivo	string	SEFAZ 마지막 반환 메시지
stats.resNFe	int	이 실행에서 다운로드한 NFe 요약 수
stats.procNFe	int	다운로드한 전체 NFe 수
stats.resEvento	int	다운로드한 이벤트 요약 수
stats.procEvento	int	다운로드한 전체 이벤트 수
stats.skipped	int	건너뛴 문서 (중복 또는 개별 파싱 오류)

초기 볼륨: 한 번도 동기화하지 않은 회사는 수백에서 수천 개의 과거 문서가 있을 수 있습니다. 첫 실행은 시간이 더 걸리며 max_iterations로 중단될 수 있습니다. 응답의 pending을 확인하고 — > 0이면 다시 호출 (속도 제한 준수).

POST /api/invoice/received/list

캡처된 문서 (NFe와 이벤트) 목록

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

{
  "cnpj": "26638419000167",
  "doc_type": "resNFe",
  "chave": "",
  "emitente_cnpj": "",
  "start_create_time": "01/05/2026",
  "end_create_time": "31/05/2026",
  "page": 1,
  "page_size": 20
}

필드

필드	유형	필수	설명
cnpj	string	아니오	수신자 CNPJ(자사 CNPJ)로 필터링. 생략 시 사용자의 모든 항목
doc_type	string	아니오	문서 유형별 필터: `resNFe`, `procNFe`, `resEvento` 또는 `procEvento`
chave	string	아니오	액세스 키 (44자리)로 필터링
emitente_cnpj	string	아니오	NF-e 발행자 CNPJ (공급업체)로 필터링
start_create_time	string/long	아니오	시작 날짜. `"dd/MM/yyyy"`, ISO 또는 Unix 타임스탬프 허용
end_create_time	string/long	아니오	종료 날짜. 같은 형식
page	int	아니오	페이지 번호 (기본 `1`)
page_size	int	아니오	페이지당 항목 수 (기본 `20`, 최대 `100`)

성공 응답

{
  "success": true,
  "message": "成功",
  "data": {
    "total": 3,
    "page": 1,
    "page_size": 20,
    "list": [
      {
        "id": "6a04a70d3201b5a62f3ac2f8",
        "nsu": 2318,
        "doc_type": "resNFe",
        "schema": "resNFe_v1.01.xsd",
        "chave": "35260563845920000120550020000085471156822656",
        "cnpj_destinatario": "26638419000167",
        "emitente_cnpj": "63845920000120",
        "emitente_nome": "MEGA ONLINE LTDA",
        "valor": 1.00,
        "dh_emi": "2026-05-13 14:05:35",
        "serie": 0,
        "number": 0,
        "tp_nf": 1,
        "c_sit_nfe": 3,
        "tp_evento": 0,
        "desc_evento": "",
        "n_seq_evento": 0,
        "dh_evento": null,
        "xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml",
        "create": "2026-05-13 16:30:05"
      }
    ]
  }
}

응답 필드

필드	유형	설명
total	int	필터 조건과 일치하는 레코드 총 개수
page	int	현재 페이지
page_size	int	페이지 크기
list[].id	string	내부 ObjectId (`/received/get_xml`에서 사용)
list[].nsu	long	SEFAZ가 이 문서에 할당한 NSU
list[].doc_type	string	문서 유형: `resNFe`, `procNFe`, `resEvento`, `procEvento`
list[].schema	string	문서 스키마 (예 `resNFe_v1.01.xsd`)
list[].chave	string	NF-e 액세스 키 (44자리)
list[].cnpj_destinatario	string	수신자 CNPJ (자사 CNPJ)
list[].emitente_cnpj	string	NF-e 발행자 CNPJ (공급업체)
list[].emitente_nome	string	발행자 회사명
list[].valor	decimal	NF-e 총액 (`vNF`)
list[].dh_emi	string	NF-e 발행 일시
list[].serie	int	NF-e 시리즈 (`procNFe`에서만 채워짐)
list[].number	long	NF-e 번호 (`procNFe`에서만 채워짐)
list[].tp_nf	int	거래 유형: `0`=입고, `1`=출고 (발행자 관점)
list[].c_sit_nfe	int	NF-e 상태 (`resNFe` 내): `1`=승인, `2`=거부, `3`=취소
list[].tp_evento	int	이벤트 코드 (`resEvento`/`procEvento` 내). 예: `110110`=CC-e, `110111`=취소, `210210`=인지
list[].desc_evento	string	이벤트 텍스트 설명
list[].n_seq_evento	int	이벤트 시퀀스
list[].dh_evento	string	이벤트 일시 (이벤트만)
list[].xml_url	string	OSS의 문서 XML 공개 URL
list[].create	string	캡처 UTC 타임스탬프

정렬: 레코드는 NSU 내림차순(최신 항목 우선)으로 반환됩니다.

POST /api/invoice/received/get_xml

특정 수신 문서의 XML URL 가져오기

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

{
  "id": "6a04a70d3201b5a62f3ac2f8"
}

필드

필드	유형	필수	설명
id	string	예	문서의 ObjectId — `/received/list`에서 반환됨

성공 응답

{
  "success": true,
  "message": "data",
  "data": {
    "id": "6a04a70d3201b5a62f3ac2f8",
    "nsu": 2318,
    "doc_type": "resNFe",
    "chave": "35260563845920000120550020000085471156822656",
    "xml_url": "https://storage.../received/13-05-2026/...resNFe_2318.xml"
  }
}

반환되는 XML 정보:

resNFe — XML은 요약일 뿐, 상품/세금이 포함되지 않습니다. 인지 전 감사/선별용
procNFe — 발행 시 생성된 것과 동일한 전체 서명 XML. 클라이언트의 ERP에 가져오기 준비됨
procEvento — 서명 및 프로토콜이 포함된 전체 이벤트 XML

일반적인 오류

메시지	원인
id inválido	값이 유효한 ObjectId가 아님
documento recebido não encontrado	ObjectId는 존재하지만 토큰의 사용자에 속하지 않음

POST /api/invoice/received/get_sync_status

현재 DistDFe 동기화 상태 확인 (SEFAZ 호출 안 함)

필수 헤더

헤더	유형	설명
token	string	회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프 (초 단위, 5분 윈도우)

Payload

{
  "cnpj": "26638419000167"
}

필드

필드	유형	필수	설명
cnpj	string	예	수신자 회사 CNPJ — 14자리, 형식 없음

응답 — 이미 동기화된 회사

{
  "success": true,
  "message": "成功",
  "data": {
    "cnpj": "26638419000167",
    "uf": "SP",
    "ult_nsu": 2323,
    "max_nsu": 2323,
    "pending": 0,
    "last_sync": "2026-05-13 16:30:05"
  }
}

응답 — 동기화되지 않은 회사

{
  "success": true,
  "message": "成功",
  "data": {
    "cnpj": "26638419000167",
    "ult_nsu": 0,
    "max_nsu": 0,
    "pending": 0,
    "last_sync": null
  }
}

응답 필드

필드	유형	설명
cnpj	string	조회된 CNPJ
uf	string	마지막 동기화에서 사용된 수신자 주(州) 코드 (동기화하지 않은 경우 없음)
ult_nsu	long	마지막으로 처리된 NSU. `0` = 동기화하지 않음
max_nsu	long	마지막 동기화 시 SEFAZ에서 사용 가능한 최대 NSU
pending	long	보류 중인 문서 (`max_nsu - ult_nsu`). > 0이면 SEFAZ에 새 문서가 있음
last_sync	string	마지막 성공한 동기화의 UTC 일시. 동기화하지 않은 경우 `null`

일반적인 사용: /received/sync를 호출하기 전에 이 엔드포인트를 호출하여 SEFAZ 호출 필요성을 판단합니다. 이 엔드포인트는 SEFAZ 속도 제한을 사용하지 않으며 — 로컬 MongoDB 상태만 읽습니다.

local_shipping MDF-e — 전자 세무 문서 매니페스트

MDF-e API(모델 58, PL-MDFe 3.00 레이아웃)는 운송 매니페스트 발행, 조회, 취소 및 종료를 지원합니다. MDF-e는 운송 작업과 연결된 NF-e 및/또는 CT-e를 집계하며 도로, 항공, 수상, 철도의 4가지 모달을 지원합니다. 모든 운영 정보(운전자, 차량, 계약자, CIOT, 통행료 바우처, 결제)는 /create 본문에 포함됩니다 — 발행 후 추가/변경 이벤트는 없습니다.

엔드포인트	메소드	설명
`/api/mdfe/create`	POST	MDF-e 발행
`/api/mdfe/consult`	POST	MDF-e 상태 조회
`/api/mdfe/cancel`	POST	MDF-e 취소(승인 후 24시간 이내)
`/api/mdfe/close`	POST	MDF-e 종료(여행 종료 후)

POST /api/mdfe/create

MDF-e 발행

전송된 본문에서 MDF-e를 발행합니다. serie, nMDF, cMDF, cDV, cUF, dhEmi, mod, tpEmis, procEmi, verProc 필드는 서버에서 자동으로 계산됩니다. 클라이언트는 비즈니스 필드만 전송합니다.

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프(초, 5분 윈도우)

Body — 루트

필드	유형	설명
ide *	object	MDF-e 식별
emit *	object	발행자 데이터
infModal *	object	모달 정보(4개 중 하나만: `rodo`, `aereo`, `aquav`, `ferrov`)
infDoc *	object	연결된 세무 문서
tot *	object	화물 합계
prodPred	object	주요 화물 제품
seg	array	보험 정보
lacres	array	MDF-e 봉인
autXML	array	XML 액세스 권한 있는 CNPJ/CPF
infAdic	object	추가 정보(세무 당국 및 납세자)
infRespTec	object	기술 책임자(CNPJ, 연락처, 이메일 등)

ide — 식별

필드	유형	설명
tpAmb *	int	환경: `1`=운영, `2`=호몰로게이션
tpEmit *	int	발행자 유형: `1`=운송업체, `2`=자체 화물, `3`=운송 서비스 제공자
modal *	string	모달: `"1"`=도로, `"2"`=항공, `"3"`=수상, `"4"`=철도
UFIni *	string	여행 시작 UF(2자)
UFFim *	string	여행 종료 UF
infMunCarrega[] *	array	적재 시: `[{ cMunCarrega, xMunCarrega }]`
infPercurso[]	array	경로의 UF: `[{ UFPer }]`
tpTransp	string	운송업체 유형(도로)
dhIniViagem	string	여행 시작 일시(ISO 8601)
indCanalVerde	string	그린 채널 표시
indCarregaPosterior	string	후속 적재 표시

emit — 발행자

필드	유형	설명
CNPJ ⚠	string	발행자 CNPJ(14자리)
CPF ⚠	string	발행자 CPF(11자리)
IE	string	주 등록 번호
xNome *	string	법인명
xFant	string	상호
enderEmit	object	주소: `{ xLgr, nro, xCpl, xBairro, cMun, xMun, CEP, UF, fone, email }`

infModal — 도로 모달(modal="1")

필드	유형	설명
rodo.veicTracao *	object	견인 차량: `{ placa, tara, RENAVAM, capKG, capM3, tpRod, tpCar, UF, condutor[], prop }`
rodo.veicTracao.condutor[] *	array	운전자: `[{ xNome, CPF }]` — 최소 1
rodo.veicReboque[]	array	트레일러 차량(운전자 없는 veicTracao와 동일한 구조)
rodo.infANTT	object	ANTT 정보: `{ RNTRC, infCIOT[], valePed, infContratante[], infPag[] }`
rodo.codAgPorto	string	항구 예약 코드
rodo.lacRodo[]	array	모달 봉인: `[{ nLacre }]`

infModal — 항공 모달(modal="2")

필드	유형	설명
aereo.nac *	string	항공기 국적 마크
aereo.matr *	string	항공기 등록
aereo.nVoo *	string	비행 번호
aereo.cAerEmb *	string	탑승 공항 IATA 코드
aereo.cAerDes *	string	목적지 공항 IATA 코드
aereo.dVoo *	string	비행 날짜(YYYY-MM-DD)

infModal — 수상 모달(modal="3")

필드	유형	설명
aquav.irin *	string	선박 IRIN
aquav.tpEmb *	string	선박 유형(2자리). Zeus 내부 `byte` 잘림을 피하기 위해 ≥ 10 값 사용(예: `"10"`, `"11"`)
aquav.cEmbar *	string	선박 코드
aquav.xEmbar *	string	선박 이름
aquav.nViag *	string	항해 번호. 0으로 시작할 수 없음(스키마 검증) — `"1"`, `"100"` 등.
aquav.cPrtEmb *	string	탑승 항구 코드
aquav.cPrtDest *	string	목적 항구 코드
aquav.prtTrans	string	환적 항구
aquav.tpNav	string	항해 유형
aquav.infTermCarreg[]	array	적재 터미널: `[{ cTermCarreg, xTermCarreg }]`
aquav.infTermDescarreg[]	array	하역 터미널
aquav.infEmbComb[]	array	선단 선박: `[{ cEmbComb, xBalsa }]`
aquav.infUnidCargaVazia[]	array	빈 화물 단위
aquav.infUnidTranspVazia[]	array	빈 운송 단위

infModal — 철도 모달(modal="4")

필드	유형	설명
ferrov.trem *	object	기차 데이터: `{ xPref, dhTrem, xOri, xDest, qVag }`
ferrov.vag[] *	array	화차: `[{ pesoBC, pesoR, tpVag, serie, nVag, nSeq, TU }]` — 최소 1. Zeus/SEFAZ 제약: `serie`는 정확히 3자리(100+ 사용, 예: `"100"`); `nVag`는 숫자만(내부적으로 `long`, 예: `"100001"`); `nSeq`는 선택적 1-3자리.

infDoc — 연결된 문서

필드	유형	설명
infMunDescarga[] *	array	하역 시 — 최소 1
infMunDescarga[].cMunDescarga *	string	시 IBGE 코드
infMunDescarga[].xMunDescarga *	string	시 이름
infMunDescarga[].infNFe[]	array	연결된 NF-e: `[{ chNFe, SegCodBarras, indReentrega, infUnidTransp[], peri[] }]`
infMunDescarga[].infCTe[]	array	연결된 CT-e
infMunDescarga[].infMDFeTransp[]	array	운송 MDF-e(하청)

prodPred — 주요 제품

필드	유형	설명
tpCarga *	string	화물 유형: `"01"`=고체 벌크, `"02"`=액체 벌크, `"03"`=냉장, `"04"`=컨테이너, `"05"`=일반 화물, `"06"`=신벌크, `"07"`=위험물, `"08"`=가압 벌크
xProd *	string	주요 제품 설명
cEAN	string	GTIN/EAN
NCM	string	NCM
infLotacao	object	로트: `{ infLocalCarrega{CEP,latitude,longitude}, infLocalDescarrega{...} }`

tot — 합계

필드	유형	설명
vCarga *	decimal	화물 총 가치(> 0)
cUnid *	string	단위 코드: `"01"`=KG, `"02"`=TON
qCarga *	decimal	화물 총 수량(> 0)
qCTe	int	Quantidade de 연결된 CT-e
qNFe	int	연결된 NF-e 수
qMDFe	int	연결된 MDF-e 수

* 필수 필드. ⚠ CNPJ 또는 CPF 중 하나는 필수입니다.

간소화된 예시 — 도로 모달

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "1",
            "UFIni": "SP",
            "UFFim": "ES",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ],
            "infPercurso": [
              { "UFPer": "MG" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xBairro": "CENTRO",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "rodo": {
              "veicTracao": {
                "placa": "ABC1D23",
                "tara": 8000,
                "condutor": [
                  { "xNome": "João da Silva", "CPF": "12345678909" }
                ],
                "tpRod": "01",
                "tpCar": "01"
              }
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3205200",
                "xMunDescarga": "Vila Velha",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL"
          },
          "tot": {
            "vCarga": 50000.00,
            "cUnid": "01",
            "qCarga": 1500.00
          }
        }

간소화된 예시 — 항공 모달

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "2",
            "UFIni": "SP",
            "UFFim": "RJ",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA AEREA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV AEROPORTO",
              "nro": "5000",
              "xBairro": "CUMBICA",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "aereo": {
              "nac": "PT",
              "matr": "ABC1234",
              "nVoo": "AB1234",
              "cAerEmb": "GRU",
              "cAerDes": "GIG",
              "dVoo": "2026-05-21"
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3304557",
                "xMunDescarga": "Rio de Janeiro",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL"
          },
          "tot": {
            "vCarga": 25000.00,
            "cUnid": "01",
            "qCarga": 500.00
          }
        }

간소화된 예시 — 수상 모달

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "3",
            "UFIni": "SP",
            "UFFim": "PA",
            "infMunCarrega": [
              { "cMunCarrega": "3548500", "xMunCarrega": "SANTOS" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "NAVEGACAO EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV PORTUARIA",
              "nro": "200",
              "xBairro": "PORTO",
              "cMun": "3548500",
              "xMun": "SANTOS",
              "UF": "SP"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "aquav": {
              "irin": "1234567",
              "tpEmb": "10",
              "cEmbar": "1234",
              "xEmbar": "EMBARCACAO EXEMPLO",
              "nViag": "1",
              "cPrtEmb": "BRSSZ",
              "cPrtDest": "BRBEL"
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "1501402",
                "xMunDescarga": "Belém",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "01",
            "xProd": "GRAOS DE SOJA"
          },
          "tot": {
            "vCarga": 500000.00,
            "cUnid": "02",
            "qCarga": 50.00
          }
        }

간소화된 예시 — 철도 모달

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "modal": "4",
            "UFIni": "MG",
            "UFFim": "SP",
            "infMunCarrega": [
              { "cMunCarrega": "3106200", "xMunCarrega": "BELO HORIZONTE" }
            ]
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "FERROVIA EXEMPLO LTDA",
            "enderEmit": {
              "xLgr": "AV FERROVIARIA",
              "nro": "300",
              "xBairro": "INDUSTRIAL",
              "cMun": "3106200",
              "xMun": "BELO HORIZONTE",
              "UF": "MG"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "ferrov": {
              "trem": {
                "xPref": "F123",
                "dhTrem": "2026-05-21T08:00:00-03:00",
                "xOri": "BELO HORIZONTE",
                "xDest": "SANTOS",
                "qVag": 2
              },
              "vag": [
                {
                  "pesoBC": 30.000,
                  "pesoR": 30.000,
                  "tpVag": "Gôndola",
                  "serie": "100",
                  "nVag": "100001",
                  "nSeq": "1",
                  "TU": 28.000
                },
                {
                  "pesoBC": 30.000,
                  "pesoR": 30.000,
                  "tpVag": "Gôndola",
                  "serie": "101",
                  "nVag": "100002",
                  "nSeq": "2",
                  "TU": 28.000
                }
              ]
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3548500",
                "xMunDescarga": "Santos",
                "infNFe": [
                  { "chNFe": "35260512345678000199550010000000011000000018" }
                ]
              }
            ]
          },
          "prodPred": {
            "tpCarga": "01",
            "xProd": "MINERIO DE FERRO"
          },
          "tot": {
            "vCarga": 800000.00,
            "cUnid": "02",
            "qCarga": 56.00
          }
        }

완전한 예시(모든 필드) — 도로 모달

        {
          "ide": {
            "tpAmb": 2,
            "tpEmit": 2,
            "tpTransp": "1",
            "modal": "1",
            "UFIni": "SP",
            "UFFim": "ES",
            "infMunCarrega": [
              { "cMunCarrega": "3550308", "xMunCarrega": "SAO PAULO" }
            ],
            "infPercurso": [
              { "UFPer": "MG" }
            ],
            "dhIniViagem": "2026-05-21T08:00:00-03:00",
            "indCanalVerde": "1",
            "indCarregaPosterior": "0"
          },
          "emit": {
            "CNPJ": "12345678000199",
            "IE": "123456789012",
            "xNome": "TRANSPORTADORA EXEMPLO LTDA",
            "xFant": "Exemplo Transportes",
            "enderEmit": {
              "xLgr": "RUA EXEMPLO",
              "nro": "100",
              "xCpl": "GALPAO A",
              "xBairro": "CENTRO",
              "cMun": "3550308",
              "xMun": "SAO PAULO",
              "CEP": "01001000",
              "UF": "SP",
              "fone": "1133334444",
              "email": "contato@exemplo.com"
            }
          },
          "infModal": {
            "versaoModal": "3.00",
            "rodo": {
              "infANTT": {
                "RNTRC": "12345678",
                "infCIOT": [
                  { "CIOT": "1234567890", "CNPJ": "12345678000199" }
                ],
                "valePed": {
                  "categCombVeic": "01",
                  "disp": [
                    {
                      "CNPJForn": "98765432000111",
                      "CNPJPg": "12345678000199",
                      "nCompra": "VP001",
                      "vValePed": 250.00,
                      "tpValePed": "01"
                    }
                  ]
                },
                "infContratante": [
                  {
                    "xNome": "EMPRESA CONTRATANTE LTDA",
                    "CNPJ": "11222333000144"
                  }
                ],
                "infPag": [
                  {
                    "xNome": "João da Silva",
                    "CPF": "12345678909",
                    "Comp": [
                      { "tpComp": "01", "vComp": 5000.00, "xComp": "Frete contratado" }
                    ],
                    "vContrato": 5000.00,
                    "indAltoDesemp": "1",
                    "indPag": "0",
                    "infBanc": {
                      "codBanco": "001",
                      "codAgencia": "1234",
                      "PIX": "12345678909"
                    }
                  }
                ]
              },
              "veicTracao": {
                "cInt": "VT001",
                "placa": "ABC1D23",
                "RENAVAM": "12345678901",
                "tara": 8000,
                "capKG": 25000,
                "capM3": 80,
                "prop": {
                  "CNPJ": "12345678000199",
                  "RNTRC": "12345678",
                  "xNome": "TRANSPORTADORA EXEMPLO LTDA",
                  "IE": "123456789012",
                  "UF": "SP",
                  "tpProp": "0"
                },
                "condutor": [
                  { "xNome": "João da Silva", "CPF": "12345678909" },
                  { "xNome": "Maria Souza", "CPF": "98765432100" }
                ],
                "tpRod": "01",
                "tpCar": "01",
                "UF": "SP"
              },
              "veicReboque": [
                {
                  "cInt": "VR001",
                  "placa": "DEF4G56",
                  "RENAVAM": "98765432109",
                  "tara": 3500,
                  "capKG": 30000,
                  "capM3": 90,
                  "tpCar": "02",
                  "UF": "SP"
                }
              ],
              "lacRodo": [
                { "nLacre": "LACRE001" },
                { "nLacre": "LACRE002" }
              ]
            }
          },
          "infDoc": {
            "infMunDescarga": [
              {
                "cMunDescarga": "3205200",
                "xMunDescarga": "Vila Velha",
                "infNFe": [
                  {
                    "chNFe": "35260512345678000199550010000000011000000018",
                    "SegCodBarras": "",
                    "indReentrega": "0",
                    "infUnidTransp": [
                      {
                        "tpUnidTransp": "1",
                        "idUnidTransp": "UT001",
                        "qtdRat": 100.000,
                        "lacUnidTransp": [{ "nLacre": "LACRE-UT-001" }],
                        "infUnidCarga": [
                          {
                            "tpUnidCarga": "1",
                            "idUnidCarga": "UC001",
                            "qtdRat": 100.000,
                            "lacUnidCarga": [{ "nLacre": "LACRE-UC-001" }]
                          }
                        ]
                      }
                    ],
                    "peri": []
                  }
                ]
              }
            ]
          },
          "seg": [
            {
              "infResp": {
                "respSeg": "1",
                "CNPJ": "12345678000199"
              },
              "infSeg": {
                "xSeg": "SEGURADORA EXEMPLO SA",
                "CNPJ": "55666777000188"
              },
              "nApol": "APOL-2026-001",
              "nAver": ["AV001", "AV002"]
            }
          ],
          "prodPred": {
            "tpCarga": "05",
            "xProd": "CARGA GERAL",
            "cEAN": "7891234567890",
            "NCM": "84713012",
            "infLotacao": {
              "infLocalCarrega": {
                "CEP": "01001000",
                "latitude": "-23.5505",
                "longitude": "-46.6333"
              },
              "infLocalDescarrega": {
                "CEP": "29100000",
                "latitude": "-20.3297",
                "longitude": "-40.2925"
              }
            }
          },
          "tot": {
            "qCTe": 0,
            "qNFe": 1,
            "qMDFe": 0,
            "vCarga": 50000.00,
            "cUnid": "01",
            "qCarga": 1500.00
          },
          "lacres": [
            { "nLacre": "LACRE-GERAL-001" }
          ],
          "autXML": [
            { "CNPJ": "11222333000144" }
          ],
          "infAdic": {
            "infAdFisco": "Documento emitido em conformidade com a legislação vigente",
            "infCpl": "Transporte com escolta armada"
          },
          "infRespTec": {
            "CNPJ": "12345678000199",
            "xContato": "Suporte Técnico",
            "email": "suporte@exemplo.com",
            "fone": "1133334444"
          }
        }

성공 응답

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "nMDF": 1,
            "serie": 1,
            "protocolo": "135260000123456",
            "xml": "https://storage.../mdfe/2026-05-21/35260512345678000199580010000000011000000018.xml"
          }
        }

POST /api/mdfe/consult

MDF-e 상태 조회

액세스 키를 사용해 SEFAZ에서 직접 MDF-e 상태를 조회합니다.

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body

필드	유형	설명
chMDFe *	string	MDF-e 액세스 키(44자리)

* 필수 필드.

페이로드 예시

        {
          "chMDFe": "35260512345678000199580010000000011000000018"
        }

응답

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 100,
            "xMotivo": "Autorizado o uso do MDF-e",
            "protocolo": "135260000123456",
            "dhRecbto": "2026-05-21T10:30:00-03:00",
            "encerrado": false,
            "cancelado": false
          }
        }

POST /api/mdfe/cancel

MDF-e 취소

승인된 MDF-e를 취소합니다. 창: 승인 후 최대 24시간. MDF-e가 이미 종료된 경우 허용되지 않습니다.

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body

필드	유형	설명
chMDFe *	string	MDF-e 액세스 키(44자리)
xJust *	string	취소 사유(SEFAZ 요구 사항에 따라 최소 15자)

* 필수 필드.

페이로드 예시

        {
          "chMDFe": "35260512345678000199580010000000011000000018",
          "xJust": "Cancelamento por erro no preenchimento dos dados do veiculo"
        }

응답

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a MDF-e",
            "nProt": "135260000123457",
            "dhRegEvento": "2026-05-21T11:00:00-03:00"
          }
        }

POST /api/mdfe/close

MDF-e 종료

여행이 끝나면 MDF-e를 종료합니다. 종료 후에는 더 이상 취소할 수 없습니다. dtEnc, cUF, cMun 필드는 선택 사항이며, 생략되면 시스템이 원본 MDF-e에서 추론합니다(현재 날짜, 발행자의 UF 및 시).

필수 헤더

헤더	유형	설명
token	string	발행 회사 토큰
sign	string	MD5 서명
timestamp	string	Unix 타임스탬프(초)

Body

필드	유형	설명
chMDFe *	string	MDF-e 액세스 키(44자리)
dtEnc	string	종료일(YYYY-MM-DD). 기본값: 현재 날짜
cUF	int	종료가 발생한 UF의 IBGE 코드. 기본값: 발행자의 UF
cMun	string	시 IBGE 코드 onde ocorreu o encerramento. Default: município do emitente

* 필수 필드.

페이로드 예시

        {
          "chMDFe": "35260512345678000199580010000000011000000018",
          "dtEnc": "2026-05-22",
          "cUF": 32,
          "cMun": "3205200"
        }

응답

        {
          "success": true,
          "data": {
            "chMDFe": "35260512345678000199580010000000011000000018",
            "cStat": 135,
            "xMotivo": "Evento registrado e vinculado a MDF-e",
            "nProt": "135260000123458",
            "dhRegEvento": "2026-05-22T18:00:00-03:00"
          }
        }

vpn_key SSO — 토큰을 통한 자동 로그인

기본 URL (프로덕션)

https://api.tffiscal.com

인증

Headers: sign, timestamp, token

티켓 유효기간

60초 — 일회용

SSO(싱글 사인온)를 사용하면 ERP가 사용자를 위해 TFiscal로의 직접 액세스 링크를 생성할 수 있으며, 자격 증명을 입력하지 않고도 해당 회사에 원하는 언어로 이미 인증된 상태로 접속할 수 있습니다.

작동 방식:

ERP는 회사 토큰을 보내 POST /api/sso/create_ticket을 호출합니다.
TFiscal은 일회용 불투명 티켓을 포함한 redirectUrl을 반환합니다.
ERP는 사용자의 브라우저를 해당 URL로 리디렉션합니다.
페이지가 티켓을 소비하고 사용자는 회사 패널에 자동으로 로그인됩니다.

⚠️ 보안: 실제 회사 토큰은 URL에 절대 표시되지 않습니다. 단기 티켓(60초 유효, 일회용)만 브라우저에 노출됩니다.

POST /api/sso/create_ticket

자동 로그인 링크 생성

60초 이내에 사용할 수 있는 일회용 티켓을 생성하여 사용자를 토큰에 해당하는 회사 패널에 자동으로 로그인시킵니다.

필수 헤더

Header	타입	설명
token	string	회사 토큰 (NF-e 발행에 사용되는 것과 동일)
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 초 타임스탬프 (5분 창)

Payload

{
  "token": "TOKEN_DA_EMPRESA",
  "language": "br",
  "page": "emitir_nfe"
}

필드

필드	필수	타입	설명
token	예	string	회사 토큰 (`w_company.token`) — `/api/invoice/create`에서 사용하는 것과 동일
language	아니오	string	UI 언어: `br`, `en`, `zh`, `es`, `ja`, `ko`. 기본값: `br`
page	아니오	string	로그인 후 랜딩 페이지. 허용된 값: `emitir_nfe`. 비어 있거나 누락된 경우 기본 패널(`/company/kanban`)이 열립니다.

성공 응답

{
  "success": true,
  "message": "ticket",
  "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
  "redirectUrl": "https://www.tffiscal.com/sso#ticket=nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg",
  "expiresInSeconds": 60,
  "expiresAt": "2026-04-24T18:34:56.0000000Z"
}

응답 필드

필드	타입	설명
success	boolean	티켓이 성공적으로 생성된 경우 `true`
ticket	string	불투명 티켓 (무작위, 32바이트 base64url)
redirectUrl	string	ERP가 사용자의 브라우저를 리디렉션해야 할 전체 URL
expiresInSeconds	number	유효 기간(초) (항상 60)
expiresAt	string	UTC 만료 날짜/시간 (ISO 8601)

오류 응답

메시지	원인
`Token은 필수입니다`	body에 `token` 필드가 전송되지 않음
`유효하지 않은 Token`	토큰이 등록된 회사와 일치하지 않음
`이 토큰은 여러 회사와 연결되어 있습니다. 액세스하려는 회사의 특정 토큰을 보내주세요.`	여러 회사가 있는 통합업체 토큰 — 특정 회사의 토큰을 보내주세요
`Rate limit exceeded`	동일한 토큰에 대해 분당 30회 이상 호출

POST /api/sso/consume_ticket

티켓 소비로 세션 JWT 받기

/api/sso/create_ticket로 생성된 티켓을 TFiscal 세션 JWT로 교환합니다. 이 엔드포인트는 프론트엔드(/sso 경로)에서 호출되며 sign/timestamp 헤더가 필요하지 않습니다 — 불투명 티켓 자체가 자격 증명입니다. 각 티켓은 한 번만 소비할 수 있으며 60초 후에 만료됩니다.

Body

필드	유형	설명
ticket *	string	`create_ticket`가 반환한 티켓

* 필수 필드.

페이로드 예시

        {
          "ticket": "nXk9sz6I6KHOt_OM72ZmfyU5p1eOet5k5Bd3AFZtspg"
        }

성공 응답

        {
          "success": true,
          "message": "Login succeeded",
          "access_token": "eyJhbGciOi...",
          "type": "user",
          "uid": 1234,
          "company_id": 5678,
          "language": "br",
          "page": "emitir_nfe"
        }

응답 필드

필드	유형	설명
access_token	string	세션 JWT (유효기간 365일). TFiscal 호출의 `Authorization` 헤더에서 사용
type	string	사용자 유형 (`user`, `admin` 등)
uid	int	내부 사용자 ID
company_id	int	`create_ticket`에서 선택한 회사 ID
language	string	`create_ticket`에서 선택한 언어 (항상 정규화)
page	string	대상 페이지 (설정되지 않으면 빈 문자열)

오류 응답

메시지	원인
`Ticket inválido`	Body에 `ticket` 필드 없음
`Ticket inválido ou expirado`	티켓이 존재하지 않거나 이미 소비됨, 또는 60초 만료
`Rate limit exceeded`	동일 IP에서 분당 60회 초과
`Sessão inválida`	티켓에 연결된 사용자가 더 이상 존재하지 않음

lock 제한 및 보안

티켓 특성

특성	값
유효 기간	생성 후 60초
사용	일회용 — 소비 후 재사용 불가
속도 제한	토큰당 분당 30개 티켓 · IP당 분당 60회 소비
저장소	자동 TTL이 있는 MongoDB — 만료된 티켓은 삭제됩니다

탐색 제한

SSO를 통해 인증된 사용자는 해당 회사 화면(/invoice/company/*)에 만 액세스할 수 있습니다. 다른 영역(배급업체 패널, 일반 보고서, 관리)에 액세스하려는 시도는 회사 패널로 자동 리디렉션됩니다.

로그인 후 세션

티켓을 JWT와 교환한 후 사용자는 TFiscal의 정상 세션을 가집니다(JWT는 365일 유효, 기존 로그인과 동일). 60초는 티켓 생성과 링크 열기 사이의 창일 뿐입니다 — 그 후 사용자는 로그아웃할 때까지 정상적으로 로그인된 상태를 유지합니다.

⚠️ 중요: create_ticket은 ERP에 의해 서버 측에서만 호출되어야 합니다. 브라우저에서 이 엔드포인트를 직접 호출하지 마세요 — 프론트엔드에서 회사 토큰이 노출됩니다.

badge 회계사(Contador)

회사에 연결된 회계사 등록 데이터를 조회하기 위한 API. 특정 회사를 담당하는 회계사의 전체 데이터를 가져와야 하는 외부 회계 시스템에 유용합니다.

POST /api/accountant/get_info

회사에 연결된 회계사 정보 조회

지정된 회사에 연결된 회계사의 전체 등록 데이터를 반환합니다. 회계사는 사전에 회사(동일 CNPJ)에 연결되어 있어야 하고, 제공된 이메일은 등록과 일치해야 합니다.

필수 헤더

헤더	유형	설명
token	string	회사 토큰 또는 인티그레이터 B2B 토큰
sign	string	MD5 서명: `MD5(token + path + body + timestamp)`
timestamp	string	Unix 타임스탬프(초, 5분 윈도우)

Body

필드	유형	설명
companyId *	int	토큰에 연결된 회사 ID
accountantId *	string	회계사 ObjectId (24자 16진수)
email *	string	회계사 이메일 (등록과 일치해야 함)

* 필수 필드.

페이로드 예시

      {
        "companyId": 12345,
        "accountantId": "5f3a8b9c1d2e4f5a6b7c8d9e",
        "email": "accountant@office.com"
      }

성공 응답

      {
        "success": true,
        "data": {
          "email": "accountant@office.com",
          "officeDocumentType": "CNPJ",
          "officeDocument": "12345678000199",
          "officeName": "회계 사무소 LTDA",
          "responsibleName": "김 철수",
          "crc": "SP123456/O-7",
          "accountantCpf": "12345678909",
          "workAddress": "예시 거리 100 - 중앙 - São Paulo/SP",
          "site": "https://office.com",
          "landline": "1133334444",
          "mobile": "11999998888",
          "assistantName": "박 영희",
          "assistantEmail": "younghee@office.com",
          "assistantPhone": "11988887777",
          "observations": "월~금, 9시~18시 운영"
        }
      }

응답 필드

필드	유형	설명
email	string	회계사 기본 이메일
officeDocumentType	string	사무소 문서 유형: "CNPJ" 또는 "CPF"
officeDocument	string	사무소 문서 (숫자만)
officeName	string	사무소 법인명 / 명칭
responsibleName	string	담당 회계사 이름
crc	string	CRC 번호 (브라질 지역 회계 위원회)
accountantCpf	string	회계사 CPF (숫자만)
workAddress	string	사업장 주소
site	string	사무소 웹사이트
landline	string	유선 전화
mobile	string	휴대전화
assistantName	string	비서 이름
assistantEmail	string	비서 이메일
assistantPhone	string	비서 전화
observations	string	등록 자유 메모

오류 응답

메시지	원인
会计师ID参数异常或不存在	`accountantId` 누락 또는 유효하지 않은 ObjectId
该会计师邮箱异常或不存在	`email` 무효 또는 미등록
发票账号{companyId}异常或不存在	`companyId`가 토큰 사용자에 속하지 않음
该会计师未绑定该发票账号	회계사가 지정된 회사에 연결되지 않음

NFE API 문서

중요한 API 필드

송장 발행 프로세스 흐름

1. 기업 등록

2. 정보 전송

3. 송장 발행

4. 결과 반환

5. 파일 생성

세무 검증

Success

Failure

엔드포인트 빠른 참조

성공

클라이언트 오류

서버 오류

NFE API

sync_alt System Flow

input Input Data

settings Processing

download Output

주요 엔드포인트

필수 헤더

Body

페이로드 예시

응답

필수 헤더

Body

페이로드 예시

응답

필수 헤더

Body

페이로드 예시

응답

필수 헤더

쿼리 문자열

호출 예시

응답

필수 헤더

호출 예시

응답

필수 헤더

쿼리 문자열

호출 예시

응답

필수 헤더

호출 예시

응답

응답 예시

필수 헤더

Body — 최상위 필드

Body — cliente (객체, 필수)

Body — products[] (배열, 최소 1개 항목)

Body — products[].impostos / products[].tax_info

Body — products[].ii (수입세)

Body — products[].import_declarations[]

Body — shipping_address / delivery_address (객체, 선택)

Body — transportation (객체, 선택)

Body — pag_info[] (배열, 선택)

간소화된 예시

완전한 예시 (모든 필드)

필수 헤더

쿼리 문자열

호출 예시

응답

필수 헤더

쿼리 문자열

호출 예시

응답

필수 헤더

Body

페이로드 예시

필수 헤더

Body

페이로드 예시

필수 헤더

Body

페이로드 예시

필수 헤더

Body

페이로드 예시

Body — `cliente` (객체, 필수)

Body — `products[]` (배열, 최소 1개 항목)

Body — `products[].impostos` / `products[].tax_info`

Body — `products[].ii` (수입세)

Body — `products[].import_declarations[]`

Body — `shipping_address` / `delivery_address` (객체, 선택)

Body — `transportation` (객체, 선택)

Body — `pag_info[]` (배열, 선택)

Body — `icms[]`

Body — `ipi[]`

Body — `pis[]` 및 `cofins[]`(동일 구조)

Body — `ibs_cbs[]`(세제 개혁)

Body — `is[]`(선택세)