Acumatica发票集成与Spring Boot REST接口开发技术求助

一、Acumatica系统侧准备工作 #

1. 先搞懂Acumatica核心模块逻辑 #

Acumatica的发票管理核心在**Accounts Receivable (AR，应收账款)**模块，未付发票对应模块里的Customer Invoice记录，状态标记为Open的就是未付状态。

2. 发票集成到Acumatica的两种方式 #

• 手动批量导入：适合少量发票场景，用Acumatica自带的「Import Scenarios」工具，整理好发票数据（客户ID、金额、开票日期、行项目等），匹配AR Invoice的字段模板后批量导入。
• API自动对接：适合系统级集成，步骤如下：
  • 开启API权限：进入System > Management > Enable/Disable Features，确保API Access和REST API功能已启用。
  • 创建API专用用户：在System > Security > Users新建用户，分配AR模块的发票创建、查看权限，再在用户详情的API Access标签页生成API密钥。
  • 确认API端点格式：Acumatica REST API的AR发票端点一般为 http://<你的Acumatica实例地址>/entity/Default/<版本号>/ARInvoice，比如http://acumatica-server/entity/Default/23.200.001/ARInvoice，可通过系统右上角帮助菜单里的「API Explorer」查看具体字段和请求规则。

3. 配置未付发票查询权限 #

确保API用户拥有AR Invoice的View权限，且能使用状态筛选器（允许筛选Open状态的发票）。

二、Spring Boot开发REST端点 #

1. 添加项目依赖 #

在pom.xml中引入必要依赖：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
</dependencies>

2. 配置Acumatica连接信息 #

在application.properties中写入连接参数：

acumatica.base-url=http://你的Acumatica实例地址/entity/Default/23.200.001
acumatica.username=api专用用户名
acumatica.password=api用户密码
acumatica.company-id=你的公司ID

3. 编写Acumatica API调用服务 #

创建服务类封装API调用逻辑：

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;

import java.util.Base64;

@Service
public class AcumaticaInvoiceService {
    private final RestTemplate restTemplate;
    private final String baseUrl;
    private final String username;
    private final String password;
    private final String companyId;

    public AcumaticaInvoiceService(RestTemplate restTemplate,
                                   org.springframework.core.env.Environment env) {
        this.restTemplate = restTemplate;
        this.baseUrl = env.getProperty("acumatica.base-url");
        this.username = env.getProperty("acumatica.username");
        this.password = env.getProperty("acumatica.password");
        this.companyId = env.getProperty("acumatica.company-id");
    }

    public String getUnpaidInvoices() {
        HttpHeaders headers = new HttpHeaders();
        // 基础认证
        String auth = username + ":" + password;
        String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes());
        headers.add("Authorization", "Basic " + encodedAuth);
        headers.add("Accept", "application/json");
        headers.add("Company", companyId);

        // 筛选未付发票（状态为Open）
        String url = baseUrl + "/ARInvoice?$filter=Status eq 'Open'";
        HttpEntity<String> entity = new HttpEntity<>(headers);

        ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.GET, entity, String.class);
        return response.getBody();
    }
}

4. 暴露REST端点 #

编写控制器类提供外部访问接口：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class InvoiceController {
    private final AcumaticaInvoiceService invoiceService;

    public InvoiceController(AcumaticaInvoiceService invoiceService) {
        this.invoiceService = invoiceService;
    }

    @GetMapping("/api/unpaid-invoices")
    public String getUnpaidInvoices() {
        return invoiceService.getUnpaidInvoices();
    }
}

5. 测试验证 #

启动Spring Boot应用，访问http://localhost:8080/api/unpaid-invoices，配置正确的话就能返回Acumatica中未付发票的JSON数据。

三、关键注意事项 #

• Acumatica的API版本必须和你的实例版本对应，比如23.200.001对应2023 R2版本，别搞混。
• 发票集成时要确保字段匹配准确，比如CustomerID必须是Acumatica中已存在的客户编号，否则创建发票会失败。
• 处理多行项目的发票时，要按照Acumatica API的嵌套字段格式构造请求体。

内容的提问来源于stack exchange，提问作者Dushyant Aneja